* lisp/window.el (display-buffer): Doc fix.

Fixes: debbugs:10785

2 files changed, 16 insertions, 8 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 3dabef53ebb..2f830b7447b 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-02-12  Chong Yidong  <cyd@gnu.org>
+
+        * window.el (display-buffer): Doc fix (Bug#10785).
+
 2012-02-12  Glenn Morris  <rgm@gnu.org>
 
         * term/pc-win.el (x-selection-owner-p, x-own-selection-internal)
diff --git a/lisp/window.el b/lisp/window.el
index 298310418e8..edd8a113876 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -4625,16 +4625,20 @@ buffer.  Return the window chosen for displaying BUFFER-OR-NAME,
 or nil if no such window is found.
 
 Optional argument ACTION should have the form (FUNCTION . ALIST).
-FUNCTION is either a function or a list of functions.  Each such
-function is called with two arguments: the buffer to display and
-an alist.  It should either display the buffer and return the
-window, or return nil if unable to display the buffer.
+FUNCTION is either a function or a list of functions.
+ALIST is an arbitrary association list (alist).
+
+Each such FUNCTION should accept two arguments: the buffer to
+display and an alist.  Based on those arguments, it should either
+display the buffer and return the window, or return nil if unable
+to display the buffer.
 
 The `display-buffer' function builds a function list and an alist
-from `display-buffer-overriding-action', `display-buffer-alist',
-the ACTION argument, `display-buffer-base-action', and
-`display-buffer-fallback-action' (in that order).  Then it calls
-each function in the combined function list in turn, passing the
+by combining the functions and alists specified in
+`display-buffer-overriding-action', `display-buffer-alist', the
+ACTION argument, `display-buffer-base-action', and
+`display-buffer-fallback-action' (in order).  Then it calls each
+function in the combined function list in turn, passing the
 buffer as the first argument and the combined alist as the second
 argument, until one of the functions returns non-nil.