GNU bug report logs - #67153
[PATCH 2/2] Add 5 docstrings to abbrev.el

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67153 <at> debbugs.gnu.org, gerd <at> gnu.org, rms <at> gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#67153: [PATCH 2/2] Add 5 docstrings to abbrev.el
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" <bug-gnu-emacs <at> gnu.org>
> 
> 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.

Previous Next

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