Document the new feature of 'minibuffer-with-setup-hook'

* lisp/files.el (minibuffer-with-setup-hook): Clarify how FUN is
added to `minibuffer-setup-hook'.

2 files changed, 11 insertions, 4 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 5f19c409722..4eedd4cda39 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -647,8 +647,13 @@ respectively, `show-paren-when-point-inside-paren' or
 These should be used in preference to `font-lock-fontify-buffer' when
 called from Lisp.
 
-** Macro `minibuffer-with-setup-hook' takes (:append FUN) to mean
-appending FUN to `minibuffer-setup-hook'.
+---
+** Macro `minibuffer-with-setup-hook' can optionally append a function
+to `minibuffer-setup-hook'.
+
+If the first argument of the macro is of the form `(:append FUN)',
+then FUN will be appended to `minibuffer-setup-hook', instead of
+prepending it.
 
 ** cl-lib
 *** New functions cl-fresh-line, cl-digit-char-p and cl-parse-integer.
diff --git a/lisp/files.el b/lisp/files.el
index e7f7151acbd..ea09c2a9fa4 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -1431,8 +1431,10 @@ return value, which may be passed as the REQUIRE-MATCH arg to
 
 (defmacro minibuffer-with-setup-hook (fun &rest body)
   "Temporarily add FUN to `minibuffer-setup-hook' while executing BODY.
-FUN can also be (:append FUN1), in which case FUN1 is appended to
-`minibuffer-setup-hook'.
+
+By default, FUN is prepended to `minibuffer-setup-hook'.  But if FUN is of
+the form `(:append FUN1)', FUN1 will be appended to `minibuffer-setup-hook'
+instead of prepending it.
 
 BODY should use the minibuffer at most once.
 Recursive uses of the minibuffer are unaffected (FUN is not