bug#67217: [PATCH] Improve docstring argument conventions

[Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

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