unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#32629: 26; `buffer-list-update-hook' doc string
@ 2018-09-03 20:34 Drew Adams
  2018-09-04  7:52 ` martin rudalics
                   ` (2 more replies)
  0 siblings, 3 replies; 8+ messages in thread
From: Drew Adams @ 2018-09-03 20:34 UTC (permalink / raw)
  To: 32629

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#32629: 26; `buffer-list-update-hook' doc string
  2018-09-03 20:34 Drew Adams
@ 2018-09-04  7:52 ` martin rudalics
  2018-09-10 13:23 ` Eli Zaretskii
  2019-10-03  1:45 ` Stefan Kangas
  2 siblings, 0 replies; 8+ messages in thread
From: martin rudalics @ 2018-09-04  7:52 UTC (permalink / raw)
  To: Drew Adams, 32629

 > 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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#32629: 26; `buffer-list-update-hook' doc string
  2018-09-03 20:34 Drew Adams
  2018-09-04  7:52 ` martin rudalics
@ 2018-09-10 13:23 ` Eli Zaretskii
  2019-10-03  1:45 ` Stefan Kangas
  2 siblings, 0 replies; 8+ messages in thread
From: Eli Zaretskii @ 2018-09-10 13:23 UTC (permalink / raw)
  To: Drew Adams; +Cc: 32629

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#32629: 26; `buffer-list-update-hook' doc string
       [not found] ` <<83y3c9o59k.fsf@gnu.org>
@ 2018-09-10 13:51   ` Drew Adams
  2018-09-10 14:18     ` Eli Zaretskii
  0 siblings, 1 reply; 8+ messages in thread
From: Drew Adams @ 2018-09-10 13:51 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 32629

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#32629: 26; `buffer-list-update-hook' doc string
  2018-09-10 13:51   ` bug#32629: 26; `buffer-list-update-hook' doc string Drew Adams
@ 2018-09-10 14:18     ` Eli Zaretskii
  2018-09-11  4:22       ` Richard Stallman
  0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2018-09-10 14:18 UTC (permalink / raw)
  To: Drew Adams; +Cc: 32629

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#32629: 26; `buffer-list-update-hook' doc string
       [not found]     ` <<83pnxlo2ph.fsf@gnu.org>
@ 2018-09-10 15:00       ` Drew Adams
  0 siblings, 0 replies; 8+ messages in thread
From: Drew Adams @ 2018-09-10 15:00 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 32629

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#32629: 26; `buffer-list-update-hook' doc string
  2018-09-10 14:18     ` Eli Zaretskii
@ 2018-09-11  4:22       ` Richard Stallman
  0 siblings, 0 replies; 8+ messages in thread
From: Richard Stallman @ 2018-09-11  4:22 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 32629

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







^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#32629: 26; `buffer-list-update-hook' doc string
  2018-09-03 20:34 Drew Adams
  2018-09-04  7:52 ` martin rudalics
  2018-09-10 13:23 ` Eli Zaretskii
@ 2019-10-03  1:45 ` Stefan Kangas
  2 siblings, 0 replies; 8+ messages in thread
From: Stefan Kangas @ 2019-10-03  1:45 UTC (permalink / raw)
  To: Drew Adams; +Cc: 32629

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2019-10-03  1:45 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <<a3bf93ca-f6a1-4b72-9b2e-794993f34d05@default>
     [not found] ` <<83y3c9o59k.fsf@gnu.org>
2018-09-10 13:51   ` bug#32629: 26; `buffer-list-update-hook' doc string Drew Adams
2018-09-10 14:18     ` Eli Zaretskii
2018-09-11  4:22       ` Richard Stallman
     [not found] <<<a3bf93ca-f6a1-4b72-9b2e-794993f34d05@default>
     [not found] ` <<<83y3c9o59k.fsf@gnu.org>
     [not found]   ` <<a906fe5b-ac26-4fe8-ad89-fe476c5b707a@default>
     [not found]     ` <<83pnxlo2ph.fsf@gnu.org>
2018-09-10 15:00       ` Drew Adams
2018-09-03 20:34 Drew Adams
2018-09-04  7:52 ` martin rudalics
2018-09-10 13:23 ` Eli Zaretskii
2019-10-03  1:45 ` Stefan Kangas

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).