Document changes in 'read-buffer' and 'read-buffer-function'

* doc/lispref/minibuf.texi (High-Level Completion): Document the
4th argument to 'read-buffer' and 'read-buffer-function'.

2 files changed, 17 insertions, 9 deletions

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index bf9564627d6..ead4fe982dc 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1236,14 +1236,14 @@ Lisp function.  When possible, do all minibuffer input as part of
 reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
-@defun read-buffer prompt &optional default require-match
+@defun read-buffer prompt &optional default require-match predicate
 This function reads the name of a buffer and returns it as a string.
-The argument @var{default} is the default name to use, the value to
-return if the user exits with an empty minibuffer.  If non-@code{nil},
-it should be a string, a list of strings, or a buffer.  If it is
-a list, the default value is the first element of this list.  It is
-mentioned in the prompt, but is not inserted in the minibuffer as
-initial input.
+It prompts with @var{prompt}.  The argument @var{default} is the
+default name to use, the value to return if the user exits with an
+empty minibuffer.  If non-@code{nil}, it should be a string, a list of
+strings, or a buffer.  If it is a list, the default value is the first
+element of this list.  It is mentioned in the prompt, but is not
+inserted in the minibuffer as initial input.
 
 The argument @var{prompt} should be a string ending with a colon and a
 space.  If @var{default} is non-@code{nil}, the function inserts it in
@@ -1253,6 +1253,12 @@ the minibuffer with a default value (@pxref{Programming Tips}).
 The optional argument @var{require-match} has the same meaning as in
 @code{completing-read}.  @xref{Minibuffer Completion}.
 
+The optional argument @var{predicate}, if non-@code{nil}, specifies a
+function to filter the buffers that should be considered: the function
+will be called with every potential candidate as its argument, and
+should return @code{nil} to reject the candidate, non-@code{nil} to
+accept it.
+
 In the following example, the user enters @samp{minibuffer.t}, and
 then types @key{RET}.  The argument @var{require-match} is @code{t},
 and the only buffer name starting with the given input is
@@ -1287,7 +1293,7 @@ its usual work, with the same arguments passed to @code{read-buffer}.
 
 @defopt read-buffer-completion-ignore-case
 If this variable is non-@code{nil}, @code{read-buffer} ignores case
-when performing completion.
+when performing completion while reading the buffer name.
 @end defopt
 
 @defun read-command prompt &optional default
diff --git a/etc/NEWS b/etc/NEWS
index 9c416ae7070..029e9d8392f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1221,7 +1221,9 @@ Use the INSIDE_EMACS environment variable instead.
 ** `save-excursion' does not save&restore the mark any more.
 Use `save-mark-and-excursion' if you want the old behavior.
 
-** read-buffer-function can now be called with a 4th argument (`predicate').
++++
+** `read-buffer' and `read-buffer-function' can now be called with a 4th
+argument (`predicate').
 
 ** completion-table-dynamic stays in the minibuffer.
 If you want the old behavior of calling the function in the buffer