GNU bug report logs - #28947
26.0; doc string of `window-normalize-buffer' and similar

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 28947 in the body.
You can then email your comments to 28947 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.0; doc string of `window-normalize-buffer' and similar
Date: Sun, 22 Oct 2017 13:21:38 -0700 (PDT)

The doc string does not tell anything more than what the doc of
`get-buffer' tells you.  In fact, it tells you less.

Why does the function name start with `window-'?  Is it just because it
is in file window.el?  If so, consider moving it.  If the function has
some relation to a window (I don't see anything in the code that
indicates that) then please describe that in the doc string.

It looks like this should be called something like `get-live-buffer',
and the doc string should say that if no live buffer can be found then
an error is raised.

The doc string should also say explicitly that if the arg is nil then
the current buffer is returned.

Actually, if the arg is a buffer name that names a dead buffer then that
dead buffer is returned, so that wouldn't exactly be reflected in the
name `get-live-buffer'.

I wonder why that behavior.  Should the 3rd cond branch perhaps check
that the result is a live buffer (in effect using the 2nd cond branch on
the buffer gotten)?

Similar remarks apply to function `window-normalize-frame'.  Not
specific to a window.  Mention that a nil arg returns selected frame.

And similar remarks apply to function `window-normalize-window'.
In this case the function is about windows, but the suffix `-window' is
enough.  No need for prefix `window-'.


In GNU Emacs 26.0.90 (build 3, x86_64-w64-mingw32)
 of 2017-10-13
Repository revision: 906224eba147bdfc0514090064e8e8f53160f1d4
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, 28947 <at> debbugs.gnu.org
Subject: Re: bug#28947: 26.0; doc string of `window-normalize-buffer' and
 similar
Date: Mon, 23 Oct 2017 10:06:01 +0200

> The doc string does not tell anything more than what the doc of
> `get-buffer' tells you.  In fact, it tells you less.
>
> Why does the function name start with `window-'?  Is it just because it
> is in file window.el?  If so, consider moving it.  If the function has
> some relation to a window (I don't see anything in the code that
> indicates that) then please describe that in the doc string.
>
> It looks like this should be called something like `get-live-buffer',
> and the doc string should say that if no live buffer can be found then
> an error is raised.
>
> The doc string should also say explicitly that if the arg is nil then
> the current buffer is returned.

I rewrote the doc-string as follows:

Return buffer specified by BUFFER-OR-NAME.
BUFFER-OR-NAME must be a live buffer, a string naming a live
buffer or nil which means to return the current buffer.

This function is commonly used to process the (usually optional)
"BUFFER-OR-NAME" argument of window related functions where nil
stands for the current buffer.

> Actually, if the arg is a buffer name that names a dead buffer then that
> dead buffer is returned, so that wouldn't exactly be reflected in the
> name `get-live-buffer'.
>
> I wonder why that behavior.  Should the 3rd cond branch perhaps check
> that the result is a live buffer (in effect using the 2nd cond branch on
> the buffer gotten)?

Right.  This should have been fixed in the release version.

> Similar remarks apply to function `window-normalize-frame'.  Not
> specific to a window.  Mention that a nil arg returns selected frame.

Done.

> And similar remarks apply to function `window-normalize-window'.
> In this case the function is about windows, but the suffix `-window' is
> enough.  No need for prefix `window-'.

These three functions did not have the `window-' prefix initially.  The
prefix was requested by a maintainer and added later.

Thanks for the report, martin

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

From: Drew Adams <drew.adams <at> oracle.com>
To: martin rudalics <rudalics <at> gmx.at>, 28947 <at> debbugs.gnu.org
Subject: RE: bug#28947: 26.0; doc string of `window-normalize-buffer' and
 similar
Date: Mon, 23 Oct 2017 06:16:31 -0700 (PDT)

> I rewrote the doc-string as follows:
> 
> Return buffer specified by BUFFER-OR-NAME.
> BUFFER-OR-NAME must be a live buffer, a string naming a live
> buffer or nil which means to return the current buffer.
> 
> This function is commonly used to process the (usually optional)
> "BUFFER-OR-NAME" argument of window related functions where nil
> stands for the current buffer.
> ...
> Right.  This should have been fixed in the release version.
> ...
> Done.
> ...
> These three functions did not have the `window-' prefix initially.  The
> prefix was requested by a maintainer and added later.

Thanks for the quick fix.  Too bad about the function names.
I don't really see them as normalizing anything.  And yes,
they are used by window-related functions.  But they are
general utilities, not really having anything to do with
windows.

It's a bit like having a general function such as
`get-buffer' defined in a Lisp library `foo.el',
which is about using foos, and naming it
`foo-get-buffer'.  If the function is usable and
useful outside foo.el then its definition belongs
outside foo.el, and it shouldn't have the
misleading prefix `foo-'.

This (the name) is all the more important for a library
named `window.el', as a window is an important, basic
Emacs thingie, and functions with `window' in their
name should be about Emacs windows.

Perhaps our maintainer could consider changing his
mind about this one?  Perhaps we could move these
functions out of `window.el' and rename them without
prefix `window-'?

Message #16 received at 28947-done <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Drew Adams <drew.adams <at> oracle.com>, 28947-done <at> debbugs.gnu.org
Subject: Re: bug#28947: 26.0; doc string of `window-normalize-buffer' and
 similar
Date: Tue, 31 Oct 2017 09:41:13 +0100

> Perhaps our maintainer could consider changing his
> mind about this one?  Perhaps we could move these
> functions out of `window.el' and rename them without
> prefix `window-'?

Probably people don't care much so I'm closing this bug.

Thanks, martin

Previous Next

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