bug#25581: 25.1; Incorrect statement in (elisp) `Hooks'

[npostavs]

Drew Adams <drew.adams@oracle.com> writes:
>> 
>>  If the variable's name ends in @samp{-function}, then its value is
>> +just a single function, not a list of functions.  @code{add-hook}
>> +should not be used to modify such a @emph{single function hook}
>    ^^^^^^^^^^
>> +because it would turn the value into a list.  Use @code{add-function}
>    ^^^^^^^
>> +instead (@pxref{Advising Functions}).
>
> Not in my opinion.  The fact that it automatically turns the
> value into a list is a _feature_, not something to avoid.

Perhaps an example would help clarify things:

emacs -Q
M-: (add-hook 'blink-paren-function #'ignore) RET
insert "()"
blink-paren-post-self-insert-function: Invalid function: (ignore 
blink-matching-open)

In my opinion, such errors (triggered by putting a list where a function
was wanted) are something to avoid.

> Yes, it is true that there are "single-function" hooks
> (hooks that happen to have only one function at the
> moment) and "single-function" hooks (hooks that are
> designed/expected to only ever have a single function,
> never zero or more than one).  And yes, the current
> wording is a bit ambiguous in this regard.

IMO the current wording is pretty unambiguous that a variable ending in
"-function" should be a single function and not a list.  But if you feel
differently, please suggest an alternate wording.

>
> And such code should also _document_ this (exceptional)
> need for its hook to have only a single function.

>From a quick look at M-x apropos-variable RET .*-function$ RET, every
such variable is described as "a function" or "function" which is
clearly not a list of functions.