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

Previous Next

Full log

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Tomas Nordin <tomasn <at> posteo.net>, 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 01 Sep 2024 10:34:19 -0400

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

That's an internal detail that's not observable to the caller anyway.

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

Maybe we can simplify the wording a bit by focusing less about whether
the hook's value is a function or a list of functions, and talking about
the "sequence" or "set" of functions (which can be represented by
a list of functions or a function)?

Something like:

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



- Stefan

Previous Next

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