Add docs for display-buffer action display-buffer-use-some-frame

* lisp/window.el (display-buffer-use-some-frame): improve doc string

* doc/lispref/windows.texi (Display Action Functions): add
  display-buffer-use-some-frame

* etc/NEWS: mention display-buffer-use-some-frame

3 files changed, 29 insertions, 9 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 750397c7375..41f02aabaa8 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2301,6 +2301,23 @@ the function specified in @code{pop-up-frame-function}
 is added to the newly created frame's parameters.
 @end defun
 
+@defun display-buffer-use-some-frame buffer alist
+This function tries to ``display'' @var{buffer} by trying to find a
+frame that meets a predicate (by default any frame other than the
+current frame).
+
+If @var{alist} has a non-@code{nil} @code{`inhibit-switch-frame} entry,
+avoid raising the frame.
+
+If @var{alist} has a non-nil @code{frame-predicate} entry, its value is a
+function taking one argument (a frame), returning non-nil if the
+frame is a candidate; this function replaces the default predicate.
+
+If this function chooses a window on another frame, it makes that frame
+visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
+entry (@pxref{Choosing Window Options}), raises that frame if necessary.
+@end defun
+
 @defun display-buffer-pop-up-window buffer alist
 This function tries to display @var{buffer} by splitting the largest
 or least recently-used window (typically one on the selected frame).
diff --git a/etc/NEWS b/etc/NEWS
index 5bb7a009e37..6dbe6b38b11 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -84,6 +84,11 @@ command line when `initial-buffer-choice' is non-nil.
 
 * Changes in Emacs 25.1
 
+** New display-buffer action function display-buffer-use-some-frame
+This displays the buffer in an existing frame other than the current
+frame, and allows the caller to specify a frame predicate to exclude
+frames.
+
 ** New doc command `describe-symbol'.  Works for functions, vars, faces, etc...
 
 ** `isearch' and `query-replace' now perform character folding in matches.
diff --git a/lisp/window.el b/lisp/window.el
index 986c55380d0..238e53ca76a 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6489,19 +6489,17 @@ its documentation for additional customization information."
 ;;; `display-buffer' action functions:
 
 (defun display-buffer-use-some-frame (buffer alist)
-  "Display BUFFER in an existing frame other than the current frame.
-If successful, return the window used; otherwise return nil.
+  "Display BUFFER in an existing frame that meets a predicate
+(by default any frame other than the current frame).  If
+successful, return the window used; otherwise return nil.
 
 If ALIST has a non-nil `inhibit-switch-frame' entry, avoid
 raising the frame.
 
-If ALIST has a non-nil `pop-up-frame-parameters' entry, the
-corresponding value is an alist of frame parameters to give the
-new frame.
-
-If ALIST has a non-nil `frame-predicate' entry, the corresponding
-value is a function taking one argument (a frame), returning
-non-nil if the frame is a candidate."
+If ALIST has a non-nil `frame-predicate' entry, its value is a
+function taking one argument (a frame), returning non-nil if the
+frame is a candidate; this function replaces the default
+predicate."
   (let* ((predicate (or (cdr (assoc 'frame-predicate alist))
                         (lambda (frame)
                           (and