bug#67355: Maybe update manual - Re: bug#67355: [PATCH] Add doc string to simple.el

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

>
>>  (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.