Clarify documentation of 'get-buffer-window-list'

* doc/lispref/windows.texi (Buffers and Windows): Mention that the
current window, if relevant, will be the first in the list
returned by 'get-buffer-window-list'.

* lisp/window.el (get-buffer-window-list): Doc fix.  (Bug#21305)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index f809678f5c454cdb06f67f63728d665dbaf83fd9..9cd59d705052f62fb5ecf8fa1ef10fb5db36e913 100644 (file)
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1984,7 +1984,9 @@ to eliminate this discrepancy.
 This function returns a list of all windows currently displaying
 @var{buffer-or-name}.  @var{buffer-or-name} should be a buffer or the
 name of an existing buffer.  If omitted or @code{nil}, it defaults to
-the current buffer.
+the current buffer.  If the currently selected window displays
+@var{buffer-or-name}, it will be the first in the list returned by
+this function.
 
 The arguments @var{minibuf} and @var{all-frames} have the same
 meanings as in the function @code{next-window} (@pxref{Cyclic Window

diff --git a/lisp/window.el b/lisp/window.el
index c783b0d5b10668c16f3c1982d4d1dec7a33f88e5..d39c70186013af38966a8dd76b4aaf79d9b3f8f4 100644 (file)
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -2299,8 +2299,8 @@ selected frame and no others."
 (defun get-buffer-window-list (&optional buffer-or-name minibuf all-frames)
   "Return list of all windows displaying BUFFER-OR-NAME, or nil if none.
 BUFFER-OR-NAME may be a buffer or the name of an existing buffer
-and defaults to the current buffer.  Windows are scanned starting
-with the selected window.
+and defaults to the current buffer.  If the selected window displays
+BUFFER-OR-NAME, it will be the first in the resulting list.
 
 MINIBUF t means include the minibuffer window even if the
 minibuffer is not active.  MINIBUF nil or omitted means include