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

From: Jeremy Bryant <[email-masked]>
Date: Mon, 13 Nov 2023 22:38:39 +0000

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