GNU bug report logs - #67217
[PATCH] Improve docstring argument conventions

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 67217 in the body.
You can then email your comments to 67217 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Improve docstring argument conventions
Date: Wed, 15 Nov 2023 23:47:35 +0000

[Message part 1 (text/plain, inline)]

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.

[0001-Improve-docstring-argument-conventions.patch (text/patch, attachment)]

Message #8 received at 67217 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67217 <at> debbugs.gnu.org
Subject: Re: bug#67217: [PATCH] Improve docstring argument conventions
Date: Thu, 16 Nov 2023 08:15:03 +0200

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

Message #11 received at 67217 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 67217 <at> debbugs.gnu.org
Subject: Re: bug#67217: [PATCH] Improve docstring argument conventions
Date: Thu, 16 Nov 2023 23:55:29 +0000

Eli Zaretskii <eliz <at> 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 <at> 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.

Message #16 received at 67217-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67217-done <at> debbugs.gnu.org
Subject: Re: bug#67217: [PATCH] Improve docstring argument conventions
Date: Fri, 17 Nov 2023 09:06:16 +0200

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.