GNU bug report logs - #32629
26; `buffer-list-update-hook' doc string

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 32629 in the body.
You can then email your comments to 32629 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26; `buffer-list-update-hook' doc string
Date: Mon, 3 Sep 2018 13:34:03 -0700 (PDT)

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

Message #8 received at 32629 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, 32629 <at> debbugs.gnu.org
Subject: Re: bug#32629: 26; `buffer-list-update-hook' doc string
Date: Tue, 04 Sep 2018 09:52:00 +0200

> 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

Message #11 received at 32629 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 32629 <at> debbugs.gnu.org
Subject: Re: bug#32629: 26; `buffer-list-update-hook' doc string
Date: Mon, 10 Sep 2018 16:23:35 +0300

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

Why not?

Message #14 received at 32629 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 32629 <at> debbugs.gnu.org
Subject: RE: bug#32629: 26; `buffer-list-update-hook' doc string
Date: Mon, 10 Sep 2018 06:51:31 -0700 (PDT)

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

Message #17 received at 32629 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 32629 <at> debbugs.gnu.org
Subject: Re: bug#32629: 26; `buffer-list-update-hook' doc string
Date: Mon, 10 Sep 2018 17:18:50 +0300

> Date: Mon, 10 Sep 2018 06:51:31 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 32629 <at> 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.

Message #20 received at 32629 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 32629 <at> debbugs.gnu.org
Subject: RE: bug#32629: 26; `buffer-list-update-hook' doc string
Date: Mon, 10 Sep 2018 08:00:12 -0700 (PDT)

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

Message #23 received at 32629 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 32629 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#32629: 26; `buffer-list-update-hook' doc string
Date: Tue, 11 Sep 2018 00:22:17 -0400

[[[ 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)

Message #26 received at 32629 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 32629 <at> debbugs.gnu.org
Subject: Re: bug#32629: 26; `buffer-list-update-hook' doc string
Date: Thu, 3 Oct 2019 03:45:48 +0200

tags 32629 + wontfix
close 32629
thanks

Drew Adams <drew.adams <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.