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

[Drew Adams]

>  > Returns the root-window of frame.
>  > 1. "root-window" should be "root window".
>  > 2. Root window needs to be explained - what is it?
>  > With no explanation, this doc string says nothing at all:
>  > "`frame-root-window' returns the frame's root window".
>  > 3. And the manual's don't help - `frame-root-window' is 
>  > not mentioned.
> 
> 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.

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.

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).

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.

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 don't claim expertise in this
regard, obviously. I know that you are knowledgeable about Emacs windows and are
no doubt familiar with some of this code (e.g. window.el). I would like to
understand why `frame-root-window' is used in these contexts, even if it is not
intended for my external use. Thx.