bug#32629: 26; `buffer-list-update-hook' doc string

[Eli Zaretskii]

> Date: Mon, 10 Sep 2018 06:51:31 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 32629@debbugs.gnu.org
> 
> > > The doc string should not list the functions that run the hook.
> > 
> > Why not?
> 
> Same reason we don't do that elsewhere (do we?).

I see no reason for such a stringent consistency.

> Instead we say, in the doc for each such function, that it runs the
> hook.

We don't say that for every hook, only for some, and mostly for hooks
that are called only from a single function.

> (Similarly, we don't list, in the doc for some function, all of the
> functions that might call it.)

Of course not.  But in this case doing that makes sense.

> Let me ask: Why should this doc list the functions that run the
> hook?

Because it tells one indirectly what changes are considered to "update
the buffer list".

> And do you know of other places where we do that?

I don't think this question is relevant.  We need to consider each
case separately.