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

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

[Drew Adams]

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

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

[martin rudalics]

 > 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

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

[Drew Adams]

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

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

[martin rudalics]

 > 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