GNU bug report logs - #72915
Docstrings of add-hook and remove-hook improvement?

Previous Next

Full log

Message #57 received at 72915-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Tomas Nordin <tomasn <at> posteo.net>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 72915-done <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Thu, 27 Feb 2025 22:15:09 +0000

Version: 30.1

Tomas Nordin <tomasn <at> posteo.net> writes:

> Stefan Kangas <stefankangas <at> gmail.com> writes:
>
>> Tomas Nordin <tomasn <at> posteo.net> writes:
>>
>>> Tomas Nordin <tomasn <at> posteo.net> writes:
>>>
>>>> Stefan Monnier <monnier <at> iro.umontreal.ca> 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.
>>
>> Thanks.  I think this contribution is bigger than what we can accept
>> without a copyright assignment from you to the FSF.
>>
>> Please see etc/copyright-assign.txt in emacs.git to get started.
>
> Actually I got my assignment confirmed in November last year. It took
> some time, but it should be there on file somewhere. Should I provide
> the assignment number?

No need, thanks.  I just pushed your patch to emacs-30 with the below
small change to use the imperative mood.

Thanks for the patch!  Closing this bug now.

diff --git a/lisp/subr.el b/lisp/subr.el
index d0faff73e4a..7af21125b33 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2177,8 +2177,8 @@ add-hook
 (defun remove-hook (hook function &optional local)
   "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
+Do nothing if HOOK does not currently contain FUNCTION.
+Compare 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.