[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Emanuel Berg
Subject: bug#35163: 25.1; `narrow-to-region' docstring no mention of args
Date: Tue, 09 Apr 2019 03:09:02 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux)

Basil L. Contovounesios wrote:

> [ Your Mail-Followup-To and Mail-Copies-To
>   headers seem wrong, they should point to
>   the bug address address@hidden
>   instead of address@hidden ]

[ 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

    (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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]