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

[Drew Adams]

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

What's the alternative (for users)?  `frame-root-window' is internal, and
undocumented (and I don't understand it).  But am I right that this is what
`frame-root-window' seems to be used for most of the time: testing whether the
window is alone in its frame?

> It only operates on the selected window

Agreed. (But it's not a big deal to select a window temporarily).

> and I mostly try to avoid `save-selected-window' based routines.

What is the reason you avoid it? Is it because of performance? 

I find myself using it more than I would like, but mainly I don't like all of
the debugger minutia it goes through, starting with Emacs 22 (21?). I have to
remember (and recognize) that I can skip that particular dolist or mapcar etc.
that maps over all the frames. In Emacs 20, that doesn't happen (no doubt it is
less correct).

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

Then maybe that idiom should be provided as a user function? Or maybe
one-window-p should be made more convenient in your terms, so that it can do
that?

All I mean is that this operation of telling whether a window is alone in its
frame is not something that only internal Emacs code needs to do. It is a pretty
common operation. If the only choices are (1) a function that you feel is not so
great and (2) an internal function, then you must feel that Emacs is missing
something for users, no?