bug-gnu-emacs
[Top][All Lists]
Advanced

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






reply via email to

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