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

Previous Next

Full log

View this message in rfc822 format

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Tomas Nordin <tomasn <at> posteo.net>,  Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 72915 <at> debbugs.gnu.org
Subject: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 1 Sep 2024 00:15:17 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Tomas Nordin <tomasn <at> posteo.net>
>> 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.

It makes no difference if HOOK is "first" set to nil from the POV of the
end user, I think.  The end result is that HOOK will be a list of
functions.

IOW, the point here is that `add-hook` will work even if HOOK is void,
and that aspect is preserved in the above change.

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

While the original is not ideal, I don't find this to be an improvement.
Sorry.  I'd suggest trying to reformulate it again, to make it more
direct and avoid repeating the phrase "the value of".

The wording in the manual is probably all that is needed here:

    This function removes FUNCTION from the hook variable HOOK.

In other words, we either get to assume that the user knows what a hook
is, or we can point the user to the relevant manual section to read
about it.

Previous Next

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