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

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Mon, 10 Sep 2018 06:51:31 -0700 (PDT)
> From: Drew Adams <[hidden email]>
> Cc: [hidden email]
>
> > > 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.



Reply | Threaded
Open this post in threaded view
|

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

Richard Stallman
[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > > > The doc string should not list the functions that run the hook.
  > > >
  > > > Why not?
  > >
  > > Same reason we don't do that elsewhere (do we?).

We could add a facility to find all the callers of a function.

--
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)