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

[Stefan Monnier]

Tomas Nordin [2024-09-15 11:17:55] wrote:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of
>> text editors" <bug-gnu-emacs@gnu.org> writes:
>>
>>> 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'.
>>
>> Ah, now I see that you posted this proposal.  This is a better start
>> than what I had.
>>
>> Should we install it?
>
> This is about the doc of remove-hook. What about the edits in the
> add-hook docstring, was that OK? There was a question on the bit about
> setting the HOOK to nil, but I think that was sorted out.

The `add-hook` part was OK for me, indeed.

[ I'm no great fan of that paragraph (neither the original nor the one
  you replace it with), tho, because it's a bit "too detailed" for my
  taste.  E.g. the value *always* ends up being a list of functions, and
  the parenthesis states something which sounds to me like it should be
  inferrable from the rest of the docstring.  ]


        Stefan