GNU bug report logs - #67355
[PATCH] Add doc string to simple.el

Previous Next

Full log

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

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 67355 <at> debbugs.gnu.org
Subject: Maybe update manual - Re: bug#67355: [PATCH] Add doc string to
 simple.el
Date: Wed, 22 Nov 2023 22:33:17 +0000

>
>>  (defun kill-buffer--possibly-save (buffer)
>> +  "Prompt user whether to kill BUFFER, possibly saving it first.
>> +
>> +This assumes the buffer is known to be modified."
>
> This prefers the description of what function does to describing its
> role.  I think it is better to do the opposite:
>
>     Ask the user to confirm killing of a modified BUFFER.
>
>   If the user confirms, optionally save BUFFER that is about to be
>   killed.

Is there any issue with a potential update to the manual at (elisp)
Documentation Tips, by adding a line to reflect this tip?  Let me know
and I can prepare a separate patch.


From:
     For a function, the first line should briefly answer the question,
     “What does this function do?” For a variable, the first line should
     briefly answer the question, “What does this value mean?”

     Don’t limit the documentation string to one line; use as many lines
     as you need to explain the details of how to use the function or
     variable.  Please use complete sentences for the rest of the text
     too.

To:
     For a function, the first line should briefly answer the question,
     “What does this function do?” For a variable, the first line should
     briefly answer the question, “What does this value mean?”

     Don’t limit the documentation string to one line; use as many lines
     as you need to explain the details of how to use the function or
     variable.  Please use complete sentences for the rest of the text
     too.

+    In the longer description, prefer describing the role of a function
+    as opposed to strictly what it does.

Previous Next

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