Subject: bug#67153: closed (Re: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 17 Nov 2023 08:18:02 +0000

Your bug report

#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
67153: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=67153
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el
From: Eli Zaretskii <[email-masked]>
To: Jeremy Bryant <[email-masked]>
Cc: [email-masked], [email-masked]
Date: Fri, 17 Nov 2023 10:17:12 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Jeremy Bryant <[email-masked]>
> Cc: [email-masked], [email-masked]
> Date: Thu, 16 Nov 2023 23:48:04 +0000
> 
> Thank you for your patience in explaining what is required.
> New patch attached, with comments below.

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

Please note my minor changes in the log message, and try to follow
these conventions in the future.

Subject: [PATCH 2/2] Add 5 docstrings to abbrev.el
From: Jeremy Bryant <[email-masked]>
To: [email-masked], Richard Stallman <[email-masked]>, GerdMöllmann<[email-masked]>, Stefan Monnier <[email-masked]>
Date: Mon, 13 Nov 2023 22:38:39 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

Tags: patch

This patch adds 5 docstrings to abbrev.el where there were none before.
This now completes all docstrings in this Lisp file.

The patch is a documentation patch based on emacs-29.
Please let me know if this is ready to install or if changes are needed.

>From fbe88f6dd4717ae07883dfdf8e87053008293753 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <[email-masked]>
Date: Mon, 13 Nov 2023 22:24:36 +0000
Subject: [PATCH 2/2] Add 5 docstrings to abbrev.el

* lisp/abbrev.el (prepare-abbrev-list-buffer)
(add-abbrev)
(inverse-add-abbrev)
(abbrev--describe)
(abbrev--possibly-save): Add docstrings.
---
 lisp/abbrev.el | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index e1311dbc83b..70c79c1380f 100644
--- a/lisp/abbrev.el
+++ b/lisp/abbrev.el
@@ -122,6 +122,10 @@ abbrev-table-name
     found))
 
 (defun prepare-abbrev-list-buffer (&optional local)
+  "Return *Abbrevs* buffer for the caller to select or display.
+
+LOCAL is a flag, if non-nil display only local abbrevs.
+"
   (let ((local-table local-abbrev-table))
     (with-current-buffer (get-buffer-create "*Abbrevs*")
       (erase-buffer)
@@ -333,6 +337,22 @@ add-global-abbrev
   (add-abbrev global-abbrev-table "Global" arg))
 
 (defun add-abbrev (table type arg)
+  "Define an abbrev in abbrev TABLE whose expansion is last word before point.
+If there's an active region, use that as the expansion.
+
+ARG says how many words before point to use for the expansion;
+zero means the entire region is the expansion.
+
+A negative ARG means to undefine the specified abbrev.
+
+TYPE of abbrev includes \"Global\", \"Mode\".
+
+This command reads the abbreviation from the minibuffer.
+
+See `add-global-abbrev', `add-mode-abbrev' for caller examples.
+See `inverse-add-abbrev' for the opposite task.
+
+Don't use this function in a Lisp program; use `define-abbrev' instead."
   (let ((exp
          (cond
           ((or (and (null arg) (use-region-p))
@@ -393,6 +413,18 @@ inverse-add-global-abbrev
   (inverse-add-abbrev global-abbrev-table "Global" n))
 
 (defun inverse-add-abbrev (table type arg)
+  "Define the word before point as as an abbrev in TABLE.
+
+ARG means use the ARG-th word before point as the
+abbreviation.  Negative ARG means use the ARG-th word after point.
+
+This command reads the expansion from the minibuffer, defines the
+abbrev, and then expands the abbreviation in the current buffer.
+
+TYPE of abbrev can be \"Global\", \"Mode\".
+
+See `inverse-add-global-n', `inverse-add-mode-abbrev' for caller examples.
+See also `add-abbrev', which performs the opposite task."
   (let (name exp start end)
     (save-excursion
       (forward-word (1+ (- arg)))
@@ -406,7 +438,7 @@ inverse-add-abbrev
 			   nil nil nil t))
     (when (or (not (abbrev-expansion name table))
 	      (y-or-n-p (format "%s expands into \"%s\"; redefine? "
-				name (abbrev-expansion name table))))
+                                name (abbrev-expansion name table))))
       (define-abbrev table (downcase name) exp)
       (save-excursion
 	(goto-char end)
@@ -1102,6 +1134,8 @@ abbrev--write
   (insert ")\n"))
 
 (defun abbrev--describe (sym)
+  "Describe abbrev SYM.
+Used to generate a table by `insert-abbrev-table-description'."
   (when (symbol-value sym)
     (prin1 (symbol-name sym))
     (if (null (abbrev-get sym :system))
@@ -1243,6 +1277,8 @@ edit-abbrevs-mode
   (setq font-lock-multiline nil))
 
 (defun abbrev--possibly-save (query &optional arg)
+  "Hook function for use by `save-some-buffer-functions'.
+Associated meaning for QUERY and ARG."
   ;; Query mode.
   (if (eq query 'query)
       (and save-abbrevs abbrevs-changed)
-- 
2.40.1