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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 67355 in the body.
You can then email your comments to 67355 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Add doc string to simple.el
Date: Tue, 21 Nov 2023 23:33:50 +0000

[Message part 1 (text/plain, inline)]

Tags: patch


This patch adds a doc string to simple.el where there was none.

Please confirm if this is good to install or if any refinements are
needed.  Thanks in advance.

[0001-Add-doc-string-to-simple.el.patch (text/patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67355 <at> debbugs.gnu.org
Subject: Re: bug#67355: [PATCH] Add doc string to simple.el
Date: Wed, 22 Nov 2023 16:29:21 +0200

> Date: Tue, 21 Nov 2023 23:33:50 +0000
> From:  Jeremy Bryant via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> This patch adds a doc string to simple.el where there was none.

Thanks.

> Please confirm if this is good to install or if any refinements are
> needed.  Thanks in advance.

Below.

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

Message #11 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: Re: bug#67355: [PATCH] Add doc string to simple.el
Date: Wed, 22 Nov 2023 22:23:37 +0000

[Message part 1 (text/plain, inline)]

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

Style noted, revised patch attached.

[0001-Add-doc-string-to-simple.el.patch (text/x-diff, attachment)]

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.

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

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

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 67355 <at> debbugs.gnu.org
> 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.

I added there something similar to your suggestion.  Thanks.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67355-done <at> debbugs.gnu.org
Subject: Re: bug#67355: [PATCH] Add doc string to simple.el
Date: Thu, 23 Nov 2023 17:29:44 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 67355 <at> debbugs.gnu.org
> Date: Wed, 22 Nov 2023 22:23:37 +0000
> 
> Style noted, revised patch attached.

Thanks, installed on the emacs-29 branch, and closing the bug.

Previous Next

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