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

[martin rudalics <rudalics@gmx.at>]

 > 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