bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Basil L. Contovounesios wrote:

> [ Your Mail-Followup-To and Mail-Copies-To
>   headers seem wrong, they should point to
>   the bug address 35163@debbugs.gnu.org
>   instead of bug-gnu-emacs@gnu.org. ]

[ OK, now I reply tho this (i.e., your) message
  thru gmane.emacs.bugs, and after that, I hope
  to reply to Noam Postavsky's message, and
  I'll do that thru mail, and we'll perhaps see
  if there is a difference or both ways are
  broken. My hunch is it'll work if I use mail,
  but not if I use the Gmane newsgroup. ]

[ I was right, the Gmane newsgroups is to
  blame. So I re-send it here as well.
  Now everyone should be happy and content. ]

> They're conventions and decent guidelines for
> the general case, not rules. Humans reserve
> the right to exercise their own judgement.
> In particular, the "rule" to mention
> positional arguments in the order they appear
> often makes for unreadable docstrings IME.

OK, the rule to mention them in order makes
sense especially if you have a function with
tons of args. But most important is that they
are mentioned exactly as they are, so they can
be searched for. Often, in Elisp code, you see
this


    (some-function some-feature some-property t)


Now, you can often guess what everything does,
except for the last `t'. Brining up the help
and searching for the arg's name to find it
immediately in the docstring is a good way of
finding out, fast.

Thanks for your message, I'll keep it if this
situation appears again.

> Eli [...] keeps himself very busy
> co-maintaining Emacs, yet he still manages to
> set a stellar example of how documentation
> should be maintained.

... okay? I just thought that was a strange
statement. Like someone had _denied_ that (?)

-- 
underground experts united
http://user.it.uu.se/~embe8573