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

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

[Drew Adams]

Doc string:
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". Gee thanks a
lot! `thrinblat-oag-plaz' returns the thrinblat's oag plaz.
 
3. And the manual's don't help - `frame-root-window' is not mentioned.
 

In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

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

[Drew Adams]

Note too that "root window" means something about window manager
windows (e.g. X Window), outside Emacs, so it is all the more
important to explain this concept a frame's root window.

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

[martin rudalics]

 > Doc string:
 > 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". Gee thanks a
 > lot! `thrinblat-oag-plaz' returns the thrinblat's oag plaz.
 >
 > 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.

martin

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.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Thu, 18 Jun 2009 07:05:11 -0700
> Cc: 
> Reply-To: Drew Adams <drew.adams@oracle.com>, 3598@emacsbugs.donarmstrong.com
> 
> 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 see no reason not to have doc strings for internal functions.
Emacs hackers need doc strings from time to time.  Adding "internal
use only" to the doc string is the preferred solution.

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

[Drew Adams]

> > 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 see no reason not to have doc strings for internal functions.
> Emacs hackers need doc strings from time to time.  Adding "internal
> use only" to the doc string is the preferred solution.

FWIW, I agree 100%.

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

[Lennart Borgman]

On Thu, Jun 18, 2009 at 5:17 PM, Drew Adams<drew.adams@oracle.com> wrote:
>> > 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 see no reason not to have doc strings for internal functions.
>> Emacs hackers need doc strings from time to time.  Adding "internal
>> use only" to the doc string is the preferred solution.
>
> FWIW, I agree 100%.


And I agree 150%. At least.

In every situation where the semantics of a function may be difficult
to understand it is very important to have the doc string describe it.
Otherwise both the person who programs the function and the user might
be confused.

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

[martin rudalics]

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

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?

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

[martin rudalics]

 >> and I mostly try to avoid `save-selected-window' based routines.
 >
 > What is the reason you avoid it? Is it because of performance?

Hysterical reasons.  Earlier (maybe < 2005) versions failed to restore
the current buffer and I spent hours debugging that.  I don't even know
whether all issues have been fixed by now.

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

The inherent problem of all `save-selected-window' based routines is the
selected window vs current buffer relation.  Unfortunately, there's no
perfect solution for this since sometimes you want to look at a
particular window only to check its geometry or some related settings
and IMHO `one-window-p' definitively belongs to that category.  Other
times you are interested in the buffer shown by the window as well and
there it makes well sense to make the window's buffer current too.  BTW,
in this context note how often Emacs code used to talk (and occasionally
still does) about selected buffers and current windows.

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

I most certainly do.  But I'm not sure whether it'd better to rewrite
`one-window-p' or provide a separate function.

martin