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

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

[Drew Adams]

The doc string should not list the functions that run the hook.

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.16299
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[martin rudalics]

 > The doc string should not list the functions that run the hook.

If you feel strongly about this, please submit a new doc-string.

Thanks, martin

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

[Eli Zaretskii]

> Date: Mon, 3 Sep 2018 13:34:03 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> The doc string should not list the functions that run the hook.

Why not?

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

[Stefan Kangas]

tags 32629 + wontfix
close 32629
thanks

Drew Adams <drew.adams@oracle.com> writes:

>> > > > 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.
>
> No, there's no need for a stringent consistency.
> That's generally true.
>
>> Of course not.  But in this case doing that makes sense.
>> Because it tells one indirectly what changes are considered to "update
>> the buffer list".
>
> OK. Thanks for thinking about it.

The conclusion here was that the doc string is fine as it is.  Closing.

Best regards,
Stefan Kangas

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

[Drew Adams]

> > The doc string should not list the functions that run the hook.
> 
> Why not?

Same reason we don't do that elsewhere (do we?). Instead we
say, in the doc for each such function, that it runs the hook.

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

The most that could be done would be to list the functions
known, ahead of time, to run the hook. But even that is
counterproductive, IMO.

Let me ask: Why should this doc list the functions that run the
hook? And do you know of other places where we do that?

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.

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)

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

[Drew Adams]

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

No, there's no need for a stringent consistency.
That's generally true.

> Of course not.  But in this case doing that makes sense.
> Because it tells one indirectly what changes are considered to "update
> the buffer list".

OK. Thanks for thinking about it.