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

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

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

That's an internal detail that's not observable to the caller anyway.

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

Maybe we can simplify the wording a bit by focusing less about whether
the hook's value is a function or a list of functions, and talking about
the "sequence" or "set" of functions (which can be represented by
a list of functions or a function)?

Something like:

      "Remove FUNCTION from HOOK's functions.
    HOOK should be a symbol, and FUNCTION may be any valid function.
    Does nothing if HOOK does not currently contain FUNCTION.
    Compares functions with `equal`, which means that it can be
    slow if FUNCTION is not a symbol.  See `add-hook'.



- Stefan