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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 01 Sep 2024 07:57:00 +0300

> From: Tomas Nordin <[email-masked]>
> 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.

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

(This also avoids passive tense and clarifies the wording in other
aspects.)