bug#55527: 28.1; Clearer abbrev docstrings

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sat, 21 May 2022 09:41:41 -0400
> Cc: 55527@debbugs.gnu.org
> 
> For the non-inverse commands I'd love to see the "word(s)"
> construction retained as it jumps out when skimming the docstring and
> is a bit more accurate.  So how about:
> 
>   (defun add-mode-abbrev (arg)
>   "Define a mode-specific abbrev which expands into the word(s) before point.
> 
>   (defun add-global-abbrev (arg)
>   "Define a global (all modes) abbrev which expands into word(s) before point.

This is IMO a tradeoff for the worse: it makes the first line less
clear on behalf of including information that is non-essential.

In many commands, we describe in the first line what the command does
by default, and defer the description of what ARG does to the body of
the doc string.  A random example:

  (transpose-chars ARG)

  Interchange characters around point, moving forward one character.
  With prefix arg ARG, effect is to take character before point
  and drag it forward past ARG other characters (backward if ARG negative).

add-mode-abbrev and add-global-abbrev are the main user-level entry
points into this facility, so IMO it is much more important to have
the first line be as self-explanatory as possible than to describe in
it some optional features.  After all, most users will invoke these
commands through their key bindings, thus without any prefix arg.
Moreover, some values of the prefix have the effect that isn't
captured by saying "word(s)", and I see no reason to consider those
effects less important than the effect of a positive ARG.

So I'd prefer to keep the new doc strings as they are.