bug#3598: 23.0.94; doc string of frame-root-window

[martin rudalics <rudalics@gmx.at>]

 >> IIUC `frame-root-window' was deliberately never described
 >> because up to Emacs 22 it was not always safe to call Lisp
 >> functions with an internal window as argument.  So I think
 >> this function was intended for internal use only.
 >
 > I see. Well, the doc does not reflect that, for one thing.

I only expressed my personal thoughts.  The person who wrote the
doc-string might have had other ideas.

 > If it is an internal function, then please either do not give it a doc string
 > or, preferably, give it one that calls that out explicitly, and please add a
 > comment explaining why it is internal.

I simply don't know whether that function was meant to be internal.  It
has been introduced in 1992.

 > Second, whether it is internal or not is a different matter from whether its doc
 > (in the form of doc string or comment) is accurate and helpful. As I mentioned,
 > the concept of a GNU Emacs "root window" is not explained anywhere, that I can
 > find. See the XEmacs doc that I cited, which does provide some understandable
 > doc. I don't claim that the GNU Emacs concept (which is unknown to me) is the
 > same as or even similar to the XEmacs concept (which is clearly explained).

I intend to provide a specification of window trees as soon as I have
fully understood the code that constitutes the operations allowed on
them.  This might still take some time, though.

 > IOW, internal is one thing; unexplained is another. Good explanation is in the
 > spirit of free software, even if the bottom line is the source code.

But it's sometimes hard to provide explanations for things that have
been written more than 15 years ago.  I'm no archaeologist.

 > The function `frame-root-window' seems to be used in the source code in places
 > where I might naively expect the code to use `one-window-p' (with appropriate
 > args and perhaps sometimes additional tests).

I dislike `one-window-p'.  It only operates on the selected window and I
mostly try to avoid `save-selected-window' based routines.  Moreover,
`one-window-p' calls `next-window' and it requires the knowledge of
window trees to tell whether that always DTRT in a particular context.

        (eq window (frame-root-window (window-frame window)))

is for me the most trivial way to tell whether `window' stands for
"everything but the mini stuff" on its frame.

martin