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

Previous Next

Full log

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

From: Emanuel Berg <moasenwood <at> zoho.eu>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#35163: 25.1; `narrow-to-region' docstring no mention of args
Date: Tue, 09 Apr 2019 02:45:08 +0200

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

> 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

Previous Next

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