Some fixes around `delete-other-frames' and `next-frame'

* src/frame.c (Fdelete_frame): Clarify doc-string.
* lisp/frame.el (delete-other-frames): Delete other frames on
FRAME's terminal instead of the current terminal.  Delete
non-minibuffer-only surrogate frames too.  See
http://lists.gnu.org/archive/html/emacs-devel/2016-08/msg00467.html
* doc/lispref/frames.texi (Deleting Frames): Minor fixes for
docs of `delete-frame' and `frame-live-p'.  Add entry for
`delete-other-frames'.
(Finding All Frames): Fix doc of `next-frame'.

1 files changed, 22 insertions, 12 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 15a9bd911f..53406d114a 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1904,10 +1904,11 @@ to it.
 
 @deffn Command delete-frame &optional frame force
 @vindex delete-frame-functions
-This function deletes the frame @var{frame}.  Unless @var{frame} is a
-tooltip, it first runs the hook @code{delete-frame-functions} (each
-function gets one argument, @var{frame}).  By default, @var{frame} is
-the selected frame.
+This function deletes the frame @var{frame}.  The argument @var{frame}
+must specify a live frame (see below) and defaults to the selected
+frame.  Unless @var{frame} specifies a tooltip, this function first runs
+the hook @code{delete-frame-functions} (each function getting one
+argument, @var{frame}).
 
 A frame cannot be deleted as long as its minibuffer serves as surrogate
 minibuffer for another frame (@pxref{Minibuffers and Frames}).
@@ -1916,9 +1917,9 @@ but if @var{force} is non-@code{nil}, then you are allowed to do so.
 @end deffn
 
 @defun frame-live-p frame
-The function @code{frame-live-p} returns non-@code{nil} if the frame
-@var{frame} has not been deleted.  The possible non-@code{nil} return
-values are like those of @code{framep}.  @xref{Frames}.
+This function returns non-@code{nil} if the frame @var{frame} has not
+been deleted.  The possible non-@code{nil} return values are like those
+of @code{framep}.  @xref{Frames}.
 @end defun
 
   Some window managers provide a command to delete a window.  These work
@@ -1927,6 +1928,15 @@ When Emacs gets one of these commands, it generates a
 @code{delete-frame} event, whose normal definition is a command that
 calls the function @code{delete-frame}.  @xref{Misc Events}.
 
+@deffn Command delete-other-frames &optional frame
+This command deletes all frames on @var{frame}'s terminal, except
+@var{frame}.  If @var{frame} uses another frame's minibuffer, that
+minibuffer frame is left untouched.  The argument @var{frame} must
+specify a live frame and defaults to the selected frame.  Internally,
+this command works by calling @code{delete-frame} with @var{force}
+@code{nil} for all frames that shall be deleted.
+@end deffn
+
 @node Finding All Frames
 @section Finding All Frames
 @cindex frames, scanning all
@@ -1946,11 +1956,11 @@ visible, even though only the selected one is actually displayed.
 @end defun
 
 @defun next-frame &optional frame minibuf
-This function lets you cycle conveniently through all the frames on
-the current display from an arbitrary starting point.  It returns the
-next frame after @var{frame} in the cycle.  If @var{frame} is
-omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
-Focus}).
+This function lets you cycle conveniently through all the frames on a
+specific terminal from an arbitrary starting point.  It returns the
+frame following @var{frame}, in the list of all live frames, on
+@var{frame}'s terminal.  The argument @var{frame} must specify a live
+frame and defaults to the selected frame.
 
 The second argument, @var{minibuf}, says which frames to consider: