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

[Tomas Nordin]

Stefan Kangas  writes:

> Stefan Kangas  writes:
>
>> The wording in the manual is probably all that is needed here:
>>
>> This function removes FUNCTION from the hook variable HOOK.
>
> BTW.  Here's another idea:
>
> If HOOK is a list of functions, remove FUNCTION from that list.
>
> If HOOK is equal to FUNCTION, set HOOK to nil.
>
> Otherwise do nothing.

I like that, adjusted maybe to respect Stefan M's nitpick:

If HOOK's value is a list of functions, remove FUNCTION from that list.
If HOOK's value is FUNCTION, set HOOK to nil.
Otherwise do nothing.

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

[Tomas Nordin]

Hello List

In bug#70820 August 14, Stefan mentions that it is a common confusion to
think of the functions in a hook as hooks. It got my attention because I
belong to the confused ones every second year or so adding or removing
functions from a hook.

I suggest the provided patch as a small improvement of the function
documentation of add-hook and remove-hook. Maybe it doesn't mitigate the
confusion mentioned that much, but it seem to align better with the
manual as I read it.

What do you think?

In add-hook doc, lift up the paragraph about HOOK and FUNCTION and
remove the mention about first setting the HOOK to nil. I think that is
something internal to the add-hook function and not relevant to the
programmer calling the add-hook function? And then say that the
resulting hook will be a list both when the HOOK symbol is void or a
single function.

In remove-hook, stick to the notion that a hook contain functions to
run, not hooks.

This notion though is a bit confusing in relation to the names of those
functions, but that's another story I guess.

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.
-
 FUNCTION may be any valid function, but it's recommended to use a
 function symbol and not a lambda form.  Using a symbol will
 ensure that the function is not re-added if the function is
@@ -2179,7 +2179,7 @@ remove-hook
   "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'.
 
 The optional third argument, LOCAL, if non-nil, says to modify
 the hook's buffer-local value rather than its default value.