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

[Drew Adams <drew.adams@oracle.com>]

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

What can mislead is "such a single-function hook", even though it
is used just after introducing variables named `*-function'.  If
the text is changed to repeat that name criterion then I think it
is clearer.  Something like this:

 If the name of the variable ends in `-function' (singular) then its
 value must be a function, not a list of functions.  In this case,
 to modify the variable value just set it (using `setq' etc.) or
 advise it (using `add-function' etc.).

And yes, I was wrong to say that you could in fact use `add-hook'
in this case.  Sorry for that noise.

The changes needed, I think, are (1) clarify that the requirement
of the value being a function applies only to `*-function' vars
and (2) be clear that there are multiple ways to change the value,
including plain old `setq' (as Mark O pointed out).