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