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