From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 19 Nov 2018 18:31:49 +0000 (+0200)
Subject: Improve documentation of the window tree
X-Git-Tag: emacs-26.1.91~102
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=60457d7;p=emacs.git

Improve documentation of the window tree

* doc/lispref/windows.texi (Windows and Frames): More accurate
wording regarding the relation of a mini-window to its frame's
window tree.

* src/window.h (struct window): Improve commentary to some
fields.
---

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 46f106838a5..04689f1c5e2 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -198,12 +198,13 @@ relationships between live windows.  The root node of a window tree is
 called the @dfn{root window}.  It can be either a live window (if the
 frame has just one window), or an internal window.
 
-  A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
-frame's window tree unless the frame is a minibuffer-only frame.
-Nonetheless, most of the functions in this section accept the
-minibuffer window as an argument.  Also, the function
-@code{window-tree} described at the end of this section lists the
-minibuffer window alongside the actual window tree.
+  A minibuffer window (@pxref{Minibuffer Windows}) that is not alone
+on its frame does not have a parent window, so it strictly speaking is
+not part of its frame's window tree.  Nonetheless, it is a sibling
+window of the frame's root window, and thus can be reached via
+@code{window-next-sibling}.  Also, the function @code{window-tree}
+described at the end of this section lists the minibuffer window
+alongside the actual window tree.
 
 @defun frame-root-window &optional frame-or-window
 This function returns the root window for @var{frame-or-window}.  The
diff --git a/src/window.h b/src/window.h
index 629283ac40c..c7f525e2704 100644
--- a/src/window.h
+++ b/src/window.h
@@ -93,12 +93,14 @@ struct window
     /* The frame this window is on.  */
     Lisp_Object frame;
 
-    /* Following (to right or down) and preceding (to left or up) child
-       at same level of tree.  */
+    /* Following (to right or down) and preceding (to left or up)
+       child at same level of tree.  Whether this is left/right or
+       up/down is determined by the 'horizontal' flag, see below.
+       A minibuffer window has the frame's root window pointed by 'prev'.  */
     Lisp_Object next;
     Lisp_Object prev;
 
-    /* The window this one is a child of.  */
+    /* The window this one is a child of.  For a minibuffer window: nil.  */
     Lisp_Object parent;
 
     /* The normal size of the window.  These are fractions, but we do
@@ -113,7 +115,9 @@ struct window
     Lisp_Object new_normal;
     Lisp_Object new_pixel;
 
-    /* May be buffer, window, or nil.  */
+    /* For a leaf window: a buffer; for an internal window: a window;
+       for a pseudo-window (such as menu bar or tool bar): nil.  It is
+       a buffer for a minibuffer window as well.  */
     Lisp_Object contents;
 
     /* A marker pointing to where in the text to start displaying.