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

From: Eli Zaretskii <[email-masked]>
Date: Tue, 14 Nov 2023 16:17:54 +0200

> Date: Mon, 13 Nov 2023 22:38:39 +0000
> From:  Jeremy Bryant via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> 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.

Thanks, see a few comments below.

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

That newline before the closing quote is redundant,

>  (defun add-abbrev (table type arg)
> +  "Define an abbrev in abbrev TABLE whose expansion is last word before point.

The first sentence of a doc string should preferably mention the
mandatory arguments (TYPE and ARG).  If the result is too long to fit
on a single line, consider saying only the main part there, and then
describing the details in the following lines.

> +TYPE of abbrev includes \"Global\", \"Mode\".

"Includes"? are there other types?

>  (defun inverse-add-abbrev (table type arg)
> +  "Define the word before point as as an abbrev in TABLE.
                                   ^^^^^
Typo.

> +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."

Same comments here.