[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 02:45:08 +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 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. ]
> 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
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, (continued)
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Eli Zaretskii, 2019/04/05
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/05
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Eli Zaretskii, 2019/04/06
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/06
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Eli Zaretskii, 2019/04/06
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/06
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Glenn Morris, 2019/04/08
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Eli Zaretskii, 2019/04/08
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/08
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Basil L. Contovounesios, 2019/04/08
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args,
Emanuel Berg <=
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/08
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Basil L. Contovounesios, 2019/04/08
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/09
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Robert Pluim, 2019/04/09
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/09
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Robert Pluim, 2019/04/09
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/09
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Robert Pluim, 2019/04/11
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Emanuel Berg, 2019/04/12
- bug#35163: 25.1; `narrow-to-region' docstring no mention of args, Eli Zaretskii, 2019/04/09