Fix documentation of 'balance-windows'

* lisp/window.el (balance-windows): Doc fix.

* doc/emacs/windows.texi (Change Window): Make the description of
'balance-windows' more accurate.  (Bug#71915)

2 files changed, 13 insertions, 8 deletions

diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 5ad6850fed9..60599d42020 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -300,7 +300,8 @@ Make selected window narrower (@code{shrink-window-horizontally}).
 Shrink this window if its buffer doesn't need so many lines
 (@code{shrink-window-if-larger-than-buffer}).
 @item C-x +
-Make all windows the same height (@code{balance-windows}).
+Balance the sizes of all the windows of the selected frame
+(@code{balance-windows}).
 @end table
 
 @kindex C-x 0
@@ -373,8 +374,11 @@ lines to other windows in the frame.
 
 @kindex C-x +
 @findex balance-windows
-  You can also use @kbd{C-x +} (@code{balance-windows}) to even out the
-heights of all the windows in the selected frame.
+  You can also use @kbd{C-x +} (@code{balance-windows}) to balance the
+sizes of all the windows of the selected frame (with the exception of
+the minibuffer window, @pxref{Minibuffer}).  This command makes each
+horizontal pair of adjacent windows the same height, and each vertical
+pair of adjacent windows the same width.
 
 @node Displaying Buffers
 @section Displaying a Buffer in a Window
diff --git a/lisp/window.el b/lisp/window.el
index 0dc9421fde7..60040f18bc7 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -5888,12 +5888,13 @@ is non-nil)."
               (setq sub (window-right sub))))))))
 
 (defun balance-windows (&optional window-or-frame)
-  "Balance the sizes of windows of WINDOW-OR-FRAME.
-WINDOW-OR-FRAME is optional and defaults to the selected frame.
+  "Balance the sizes of windows shown on the selected frame.
+When called from Lisp, WINDOW-OR-FRAME is optional and defaults to the
+selected frame.
 If WINDOW-OR-FRAME denotes a frame, balance the sizes of all
-windows of that frame.  If WINDOW-OR-FRAME denotes a window,
-recursively balance the sizes of all child windows of that
-window."
+windows of that frame's root window (which excludes the mini-window).
+If WINDOW-OR-FRAME denotes a window, recursively balance the sizes
+of all child windows of that window."
   (interactive)
   (let* ((window
           (cond