From: Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 67217@debbugs.gnu.org
Subject: bug#67217: [PATCH] Improve docstring argument conventions
Date: Thu, 16 Nov 2023 23:55:29 +0000 [thread overview]
Message-ID: <87v8a1tfoo.fsf@jeremybryant.net> (raw)
In-Reply-To: <83y1eyp6l4.fsf@gnu.org>
Eli Zaretskii <eliz@gnu.org> writes:
>> Date: Wed, 15 Nov 2023 23:47:35 +0000
>> From: Jeremy Bryant via "Bug reports for GNU Emacs,
>> the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>>
>> Eli, following this convention mentioned in a recent bug,
>>
>> > The first sentence of a doc string should preferably mention the
>> > mandatory arguments (TYPE and ARG). If the result is too long to fit
>> > on a single line, consider saying only the main part there, and then
>> > describing the details in the following lines.
>>
>> It doesn't appear to me to be in the manual.
>
> Yes, it does:
>
> • The first line should mention all the important arguments of the
> function, and should mention them in the order that they are
> written in a function call. If the function has many arguments,
> then it is not feasible to mention them all in the first line; in
> that case, the first line should mention the first few arguments,
> including the most important arguments.
>
>> diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
>> index f760b2554f0..9f1c15525cb 100644
>> --- a/doc/lispref/tips.texi
>> +++ b/doc/lispref/tips.texi
>> @@ -642,7 +642,8 @@ Documentation Tips
>> in a function call. If the function has many arguments, then it is
>> not feasible to mention them all in the first line; in that case, the
>> first line should mention the first few arguments, including the most
>> -important arguments.
>> +important arguments. Mandatory arguments should be documented before
>> +optional arguments.
>
> What you suggest to add is already there: it says to mention the
> arguments in the order they are written in the signature, which means
> mandatory first, then the optional ones (if they are important
> enough).
>
> What I said was the usual interpretation of "most important", nothing
> more, nothing less. My intent was that the optional variables don't
> need to be mentioned if that is somehow unneeded or impractical or
> something else, but the mandatory ones should generally be mentioned.
> The manual says the same using a different wording.
>
> So let me turn the table and ask you: why did you think the existing
> text is insufficient in this aspect?
I thought your wording was clearer than the manual and proposed adapting
the manual to your wording and to be more explicit about mandatory and optional.
I accept that it is comparable.
next prev parent reply other threads:[~2023-11-16 23:55 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-11-15 23:47 bug#67217: [PATCH] Improve docstring argument conventions Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-11-16 6:15 ` Eli Zaretskii
2023-11-16 23:55 ` Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors [this message]
2023-11-17 7:06 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87v8a1tfoo.fsf@jeremybryant.net \
--to=bug-gnu-emacs@gnu.org \
--cc=67217@debbugs.gnu.org \
--cc=eliz@gnu.org \
--cc=jb@jeremybryant.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.