bug#72915: Docstrings of add-hook and remove-hook improvement?

[Stefan Kangas <stefankangas@gmail.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Tomas Nordin <tomasn@posteo.net>
>> Date: Sat, 31 Aug 2024 12:36:22 +0000
>>
>> The following on top of emacs-30.
>>
>> diff --git a/lisp/subr.el b/lisp/subr.el
>> index 28ba30f584e..e60c4119c60 100644
>> --- a/lisp/subr.el
>> +++ b/lisp/subr.el
>> @@ -2090,6 +2090,10 @@ add-hook
>>    "Add to the value of HOOK the function FUNCTION.
>>  FUNCTION is not added if already present.
>>
>> +HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
>> +single function, it is changed to a list of functions (containing only
>> +FUNCTION in the void case).
>> +
>>  The place where the function is added depends on the DEPTH
>>  parameter.  DEPTH defaults to 0.  By convention, it should be
>>  a number between -100 and 100 where 100 means that the function
>> @@ -2108,10 +2112,6 @@ add-hook
>>  buffer-local value.  That acts as a flag to run the hook
>>  functions of the global value as well as in the local value.
>>
>> -HOOK should be a symbol.  If HOOK is void, it is first set to
>> -nil.  If HOOK's value is a single function, it is changed to a
>> -list of functions.
>> -
>
> Is the bit about setting HOOK to nil incorrect?  Because the new text
> drops that part.

It makes no difference if HOOK is "first" set to nil from the POV of the
end user, I think.  The end result is that HOOK will be a list of
functions.

IOW, the point here is that `add-hook` will work even if HOOK is void,
and that aspect is preserved in the above change.

>
>>    "Remove from the value of HOOK the function FUNCTION.
>>  HOOK should be a symbol, and FUNCTION may be any valid function.  If
>>  FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
>> -list of hooks to run in HOOK, then nothing is done.  See `add-hook'.
>> +list of functions to run in HOOK, then nothing is done.  See `add-hook'.
>
> "list of functions to run in HOOK" is ambiguous wrt what "in HOOK"
> refers to.  I would rephrase:
>
>   If FUNCTION is not the value of HOOK and is not a member of the list
>   that is the value of HOOK, do nothing.

While the original is not ideal, I don't find this to be an improvement.
Sorry.  I'd suggest trying to reformulate it again, to make it more
direct and avoid repeating the phrase "the value of".

The wording in the manual is probably all that is needed here:

    This function removes FUNCTION from the hook variable HOOK.

In other words, we either get to assume that the user knows what a hook
is, or we can point the user to the relevant manual section to read
about it.