Fix description of 'display-buffer-in-previous-window' again (Bug#36161)

* lisp/window.el (display-buffer-in-previous-window): Make
doc-string more explicit (Bug#36161).
* doc/lispref/windows.texi (Buffer Display Action Functions):
Make description of 'display-buffer-in-previous-window' more
explicit.
(Buffer Display Action Alists): Mention
'display-buffer-in-previous-window' in description of
'reusable-frames' entry.

2 files changed, 52 insertions, 20 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 3116659cd03..ea9329e0517 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2581,25 +2581,47 @@ operations (@pxref{Preserving Window Sizes}).
 This function fails if no window can be split.  More often than not,
 this happens because no window is large enough to allow splitting.
 Setting @code{split-height-threshold} or @code{split-width-threshold}
-to lower values may help in this regard.  Spliting also fails when the
-selected frame has an @code{unsplittable} frame parameter;
+to lower values may help in this regard.  Splitting also fails when
+the selected frame has an @code{unsplittable} frame parameter;
 @pxref{Buffer Parameters}.
 @end defun
 
 @defun display-buffer-in-previous-window buffer alist
 This function tries to display @var{buffer} in a window where it was
-previously displayed.  If @var{alist} has a non-@code{nil}
-@code{inhibit-same-window} entry, the selected window is not eligible
-for reuse.  If @var{alist} contains a @code{reusable-frames} entry,
-its value determines which frames to search for a suitable window.
-
-If @var{alist} has a @code{previous-window} entry and the window
-specified by that entry is live and not dedicated to another buffer,
-that window will be preferred, even if it never showed @var{buffer}
+displayed previously.
+
+If @var{alist} contains a non-@code{nil} @code{inhibit-same-window}
+entry, the selected window is not eligible for use.  A dedicated
+window is usable only if it already shows @var{buffer}.  If
+@var{alist} contains a @code{previous-window} entry, the window
+specified by that entry is usable even if it never showed @var{buffer}
 before.
 
-This function will not choose the selected window if it finds another
-eligible window that has shown @var{buffer} previously.
+If @var{alist} contains a @code{reusable-frames} entry (@pxref{Buffer
+Display Action Alists}), its value determines which frames to search
+for a suitable window.  If @var{alist} contains no
+@code{reusable-frames} entry, this function searches just the selected
+frame if @code{display-buffer-reuse-frames} and @code{pop-up-frames}
+are both @code{nil}; it searches all frames on the current terminal if
+either of those variables is non-@code{nil}.
+
+If more than one window qualifies as usable according to these rules,
+this function makes a choice in the following order of preference:
+
+@itemize @bullet
+@item
+The window specified by any @code{previous-window} @var{alist} entry,
+provided it is not the selected window.
+
+@item
+A window that showed @var{buffer} before, provided it is not the
+selected window.
+
+@item
+The selected window if it is either specified by a
+@code{previous-window} @var{alist} entry or showed @var{buffer}
+before.
+@end itemize
 @end defun
 
 @defun display-buffer-use-some-window buffer alist
@@ -2786,7 +2808,9 @@ Ordering}).
 
 A major client of this is @code{display-buffer-reuse-window}, but all
 other action functions that try to reuse a window are affected as
-well.
+well.  @code{display-buffer-in-previous-window} consults it when
+searching for a window that previosuly displayed the buffer on another
+frame.
 
 @vindex inhibit-switch-frame@r{, a buffer display action alist entry}
 @item inhibit-switch-frame
diff --git a/lisp/window.el b/lisp/window.el
index c2d5b02be05..de110111b5a 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7457,10 +7457,13 @@ selected frame."
 (defun display-buffer-in-previous-window (buffer alist)
   "Display BUFFER in a window previously showing it.
 If ALIST has a non-nil `inhibit-same-window' entry, the selected
-window is not eligible for reuse.
+window is not usable.  A dedicated window is usable only if it
+already shows BUFFER.  If ALIST contains a `previous-window'
+entry, the window specified by that entry is usable even if it
+never showed BUFFER before.
 
 If ALIST contains a `reusable-frames' entry, its value determines
-which frames to search for a reusable window:
+which frames to search for a usable window:
   nil -- the selected frame (actually the last non-minibuffer frame)
   A frame   -- just that frame
   `visible' -- all visible frames
@@ -7472,12 +7475,17 @@ selected frame if `display-buffer-reuse-frames' and
 `pop-up-frames' are both nil; search all frames on the current
 terminal if either of those variables is non-nil.
 
-If ALIST has a `previous-window' entry, the window specified by
-that entry may override any other window found by the methods
-above, even if that window never showed BUFFER before.
+If more than one window is usable according to these rules,
+apply the following order of preference:
+
+- Use the window specified by any 'previous-window' ALIST entry,
+  provided it is not the selected window.
+
+- Use a window that showed BUFFER before, provided it is not the
+  selected window.
 
-Avoid using the selected window if another eligible window has
-shown BUFFER before."
+- Use the selected window if it is either specified by a
+  'previous-window' ALIST entry or showed BUFFER before."
   (let* ((alist-entry (assq 'reusable-frames alist))
 	 (inhibit-same-window
 	  (cdr (assq 'inhibit-same-window alist)))