bug#67217: [PATCH] Improve docstring argument conventions

[Jeremy Bryant]

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.