bug#67355: [PATCH] Add doc string to simple.el

bug#67355: [PATCH] Add doc string to simple.el

[Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 177 bytes --]

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.



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-doc-string-to-simple.el.patch --]
[-- Type: text/patch, Size: 791 bytes --]

From 2ca9dab72f2aacb51e0b3d6d6403c4659e168fb9 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Tue, 21 Nov 2023 23:27:44 +0000
Subject: [PATCH] Add doc string to simple.el

* lisp/simple.el (kill-buffer--possibly-save): Add doc string.
---
 lisp/simple.el | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lisp/simple.el b/lisp/simple.el
index b770d9d7d33..69d29bc306b 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -10863,6 +10863,9 @@ scratch-buffer
   (pop-to-buffer-same-window (get-scratch-buffer-create)))
 
 (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."
   (let ((response
          (cadr
           (read-multiple-choice
-- 
2.40.1

bug#67355: [PATCH] Add doc string to simple.el

[Eli Zaretskii]

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

bug#67355: [PATCH] Add doc string to simple.el

[Jeremy Bryant via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 484 bytes --]

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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-doc-string-to-simple.el.patch --]
[-- Type: text/x-diff, Size: 810 bytes --]

From 66175becbcd074333b1cd72e033b54a2c3ca061c Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Tue, 21 Nov 2023 23:27:44 +0000
Subject: [PATCH] Add doc string to simple.el

* lisp/simple.el (kill-buffer--possibly-save): Add doc string.
---
 lisp/simple.el | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lisp/simple.el b/lisp/simple.el
index b770d9d7d33..9ef348f74dc 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -10863,6 +10863,10 @@ scratch-buffer
   (pop-to-buffer-same-window (get-scratch-buffer-create)))
 
 (defun kill-buffer--possibly-save (buffer)
+  "Ask the user to confirm killing of a modified BUFFER.
+
+If the user confirms, optionally save BUFFER that is about to be
+killed."
   (let ((response
          (cadr
           (read-multiple-choice
-- 
2.40.1

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]

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

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

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: 67355@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.

bug#67355: [PATCH] Add doc string to simple.el

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: 67355@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.