bug#67217: [PATCH] Improve docstring argument conventions

bug#67217: [PATCH] Improve docstring argument conventions

[Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 563 bytes --]

Tags: patch


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.

So I'm submitting a patch to amend the manual.  This is my first patch to
the manual so let me know if this contribution is in the right section,
or needs changing before installing.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-docstring-argument-conventions.patch --]
[-- Type: text/patch, Size: 1000 bytes --]

From e6aa69b0195e413a6c93edbb931f08db2892dc47 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Wed, 15 Nov 2023 23:44:06 +0000
Subject: [PATCH] Improve docstring argument conventions

* doc/lispref/tips.texi (Documentation Tips):
Improve docstring argument procedence conventions
---
 doc/lispref/tips.texi | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

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.
 
 @item
 When a function's documentation string mentions the value of an argument
-- 
2.40.1

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?

bug#67217: [PATCH] Improve docstring argument conventions

[Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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.

bug#67217: [PATCH] Improve docstring argument conventions

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: 67217@debbugs.gnu.org
> Date: Thu, 16 Nov 2023 23:55:29 +0000
> 
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > 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.

"Mandatory" is just my personal rule of thumb, which is just easy to
explain.  But maybe you are right, and it helps explain this tip,
thanks for pointing that out.  So I've now added a note about
mandatory arguments there, in the hope that it helps.

And with that, I'm closing the bug.