bug#67217: [PATCH] Improve docstring argument conventions

[Eli Zaretskii]

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