From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Mon, 23 Aug 2021 14:32:33 +0000 (+0200)
Subject: Clarify the documentation of `next-frame'
X-Git-Tag: emacs-28.0.90~1341
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4167d4b4b2727ef9de5ad91228934eef11233e27;p=emacs.git

Clarify the documentation of `next-frame'

* doc/lispref/frames.texi (Finding All Frames): Clarify what it
means to "consider".
* src/frame.c (Fnext_frame): Rewrite doc string to say what the
parameters actually mean (bug#13339).
---

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 25706befc8d..596585f99bb 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2692,20 +2692,21 @@ frame and defaults to the selected frame.  It never returns a frame
 whose @code{no-other-frame} parameter (@pxref{Frame Interaction
 Parameters}) is non-@code{nil}.
 
-The second argument, @var{minibuf}, says which frames to consider:
+The second argument, @var{minibuf}, says which frames to include when
+considering what the next frame should be:
 
 @table @asis
 @item @code{nil}
-Exclude minibuffer-only frames.
+Include all frames except minibuffer-only frames.
 @item @code{visible}
-Consider all visible frames.
+Include only visible frames.
 @item 0
-Consider all visible or iconified frames.
+Include only visible or iconified frames.
 @item a window
-Consider only the frames using that particular window as their
+Include only the frames using that particular window as their
 minibuffer.
 @item anything else
-Consider all frames.
+Include all frames.
 @end table
 @end defun
 
diff --git a/src/frame.c b/src/frame.c
index b105268d423..c6b4c5946cb 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -1837,15 +1837,21 @@ prev_frame (Lisp_Object frame, Lisp_Object minibuf)
 
 DEFUN ("next-frame", Fnext_frame, Snext_frame, 0, 2, 0,
        doc: /* Return the next frame in the frame list after FRAME.
-It considers only frames on the same terminal as FRAME.
-By default, skip minibuffer-only frames.
-If omitted, FRAME defaults to the selected frame.
-If optional argument MINIFRAME is nil, exclude minibuffer-only frames.
-If MINIFRAME is a window, include only its own frame
-and any frame now using that window as the minibuffer.
-If MINIFRAME is `visible', include all visible frames.
-If MINIFRAME is 0, include all visible and iconified frames.
-Otherwise, include all frames.  */)
+Only frames on the same terminal as FRAME are included.  If omitted,
+FRAME defaults to the selected frame.
+
+If MINIFRAME is nil (the default), include all frames except
+minibuffer-only frames.
+
+If MINIFRAME is a window, include only its own frame and any frame now
+using that window as the minibuffer.
+
+If MINIFRAME is `visible', only include visible frames.
+
+If MINIFRAME is 0, only include visible and iconified frames.
+
+If MINIFRAME is any other value than these values, include all
+frames.  */)
   (Lisp_Object frame, Lisp_Object miniframe)
 {
   if (NILP (frame))