bug#55527: 28.1; Clearer abbrev docstrings

[Howard Melman <hmelman@gmail.com>]

On May 21, 2022, at 10:09 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> 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).

The existing docstrings for these commands had "word(s)" in them
and I don't think that's what made them unclear.  I also think it's a
common case to define an abbrev for a multi-word expansion.

I count about 80 first line docstrings in Emacs lisp code that use a "(s)" construct.
  
But looking at forward-word's docstring for inspiration, how about this:

    "Define a mode-specific abbrev which expands into ARG words before point.
    "Define a global (all modes) abbrev which expands into ARG words before point.

I think using ARG as above includes the common case of an expansion
being more than one word and defers the less common uses of
a zero or negative arg to the docstring body.  I think too that an ARG 
of zero is unclear so the user would read the body.  A negative ARG would
often reverse direction so perhaps it's unintuitive, but I think that's the case
if ARG is mentioned in the first line or not.

Also, I see now that the inverse- versions of these command treat a 
negative argument as reversing the direction to find the word to use
as the abbreviation but the (old and new) docstrings fails to mention 
this.  I'm not sure if that's intentional or not (IMO it's an odd use case).

Howard