--- Begin Message ---
|
Subject: |
[PATCH] Improve docstring argument conventions |
|
Date: |
Wed, 15 Nov 2023 23:47:35 +0000 |
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
Description: Text Data
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#67217: [PATCH] Improve docstring argument conventions |
|
Date: |
Fri, 17 Nov 2023 09:06:16 +0200 |
> 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.
--- End Message ---