Subject: bug#67217: closed (Re: bug#67217: [PATCH] Improve docstring argument conventions)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 17 Nov 2023 07:07:02 +0000

Your bug report

#67217: [PATCH] Improve docstring argument conventions

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
67217: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=67217
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#67217: [PATCH] Improve docstring argument conventions
From: Eli Zaretskii <[email-masked]>
To: Jeremy Bryant <[email-masked]>
Cc: [email-masked]
Date: Fri, 17 Nov 2023 09:06:16 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Jeremy Bryant <[email-masked]>
> Cc: [email-masked]
> Date: Thu, 16 Nov 2023 23:55:29 +0000
> 
> 
> Eli Zaretskii <[email-masked]> 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.

Subject: [PATCH] Improve docstring argument conventions
From: Jeremy Bryant <[email-masked]>
To: [email-masked]
Date: Wed, 15 Nov 2023 23:47:35 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

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.

>From e6aa69b0195e413a6c93edbb931f08db2892dc47 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <[email-masked]>
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