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

From: Tomas Nordin <[email-masked]>
Date: Thu, 27 Feb 2025 21:25:32 +0000

Tomas Nordin <[email-masked]> writes:

> Stefan Monnier <[email-masked]> writes:
>
>> 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.  ]
>
> I think I agree, the parenthesized part could be discarded, shortening
> the paragraph to
>
> "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."

I think nothing was installed along this discussion so far. Attached is
an attempt to summarize the suggestions as patch.

>From c4da167f3820c28b04da6ee28a49e307333786e6 Mon Sep 17 00:00:00 2001
From: Tomas Nordin <[email-masked]>
Date: Thu, 27 Feb 2025 22:06:25 +0100
Subject: [PATCH] ; Improve docstring of add-hook and remove-hook

* lisp/subr.el (add-hook, remove-hook):
Remove detail about setting to nil and talk about functions instead of
hooks.  (bug#72915)
---
 lisp/subr.el | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/lisp/subr.el b/lisp/subr.el
index 7263817711b..21530fc2f47 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2141,6 +2141,9 @@ 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.
+
 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
@@ -2159,10 +2162,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
@@ -2227,10 +2226,11 @@ add-hook
       (set-default hook hook-value))))
 
 (defun remove-hook (hook function &optional local)
-  "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'.
+  "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'.
 
 The optional third argument, LOCAL, if non-nil, says to modify
 the hook's buffer-local value rather than its default value.
-- 
2.39.5