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

[Drew Adams <drew.adams@oracle.com>]

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