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

Previous Next

Full log

Message #52 received at 35163 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: <35163 <at> debbugs.gnu.org>
Subject: Re: bug#35163: 25.1; `narrow-to-region' docstring no mention of args
Date: Tue, 09 Apr 2019 02:13:17 +0100

Emanuel Berg <moasenwood <at> zoho.eu> writes:

> Basil L. Contovounesios wrote:
>
>> [ Your Mail-Followup-To and Mail-Copies-To
>>   headers seem wrong, they should point to
>>   the bug address 35163 <at> debbugs.gnu.org
>>   instead of bug-gnu-emacs <at> 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. ]

Indeed, your reply to Noam correctly kept the bug report CCed, whereas
your previous reply to me did not.

>> 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.

I think most of us agree that docstrings, especially those of public
functions, should mention their accepted arguments by name, if not in
the exact same order as they appear in the argument list.  Eli fixed
this for narrow-to-region[1] following your report.

[1: a5da653319]: * src/editfns.c (Fnarrow_to_region): Doc fix.  (Bug#35163)
  2019-04-08 19:53:48 +0300
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=a5da653319a3018074debfc7b4fdd90ac7ea838c

>> 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 (?)

No-one denied that.  You said:

> Should I interpret this as "one shouldn't
> bother the maintainers with details like this"?

So my sentence was intended as an example of how un-bothered maintainers
are by details like this, in that e.g. Eli pays a lot of attention to
documenting things properly, and following Emacs and GNU conventions.

All I meant to say is that these documentation details aren't beneath
anyone.  I hope I've managed to explain myself properly.

Thanks,

-- 
Basil

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.