2 files changed, 13 insertions, 5 deletions

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index ead4fe982dc..e24d2cd643a 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1818,13 +1818,19 @@ emacs, The GNU Emacs Manual}.  Its argument list and return value are
 the same as for @code{display-sort-function}.
 @end table
 
-@defun completion-table-dynamic function
+@defun completion-table-dynamic function &optional switch-buffer
 This function is a convenient way to write a function that can act as
 a programmed completion function.  The argument @var{function} should be
 a function that takes one argument, a string, and returns an alist of
-possible completions of it.  You can think of
+possible completions of it.  It is allowed to ignore the argument and
+return a full list of all possible completions.  You can think of
 @code{completion-table-dynamic} as a transducer between that interface
 and the interface for programmed completion functions.
+
+If the optional argument @var{switch-buffer} is non-@code{nil}, and
+completion is performed in the minibuffer, @var{function} will be
+called with current buffer set to the buffer from which the minibuffer
+was entered.
 @end defun
 
 @defun completion-table-with-cache function &optional ignore-case
diff --git a/etc/NEWS b/etc/NEWS
index 029e9d8392f..34c489a1a3c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1225,10 +1225,12 @@ Use `save-mark-and-excursion' if you want the old behavior.
 ** `read-buffer' and `read-buffer-function' can now be called with a 4th
 argument (`predicate').
 
-** completion-table-dynamic stays in the minibuffer.
++++
+** `completion-table-dynamic' by default stays in the minibuffer.
+The minibuffer will be the current buffer when the function is called.
 If you want the old behavior of calling the function in the buffer
-from which the minibuffer was entered, call it with the new argument
-`switch-buffer'.
+from which the minibuffer was entered, use the new argument
+`switch-buffer' to `completion-table-dynamic'.
 
 ** window-configurations no longer record the buffers' marks.