Improve read-directory-name docstring

* lisp/files.el (read-directory-name): Improve docstring to be more
similar to that of 'read-file-name', and refer back to it where
appropriate.

(cherry picked from commit 069c8ff6d5860486ca8b97060002e80c3c4bdbc0)

diff --git a/lisp/files.el b/lisp/files.el
index a3d5d526fba2e60309b3bff15e111e3a53ba601a..e3f23231f5b2c8a9bccaa4aea564bebbf16f92ac 100644 (file)
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -871,22 +871,30 @@ See Info node `(elisp)Standard File Names' for more details."
 
 (defun read-directory-name (prompt &optional dir default-dirname mustmatch initial predicate)
   "Read directory name, prompting with PROMPT and completing in directory DIR.
-Value is not expanded---you must call `expand-file-name' yourself.
-Default name to DEFAULT-DIRNAME if user exits with the same
-non-empty string that was inserted by this function.
+The return value is not expanded---you must call `expand-file-name'
+yourself.
+
+DIR is the directory to use for completing relative file names.
+It should be an absolute directory name, or nil (which means the
+current buffer's value of `default-directory').
+
+DEFAULT-DIRNAME specifies the default directory name to return if user
+exits with the same non-empty string that was inserted by this function.
  (If DEFAULT-DIRNAME is omitted, DIR combined with INITIAL is used,
   or just DIR if INITIAL is nil.)
-If the user exits with an empty minibuffer, this function returns
-an empty string.  (This can happen only if the user erased the
-pre-inserted contents or if `insert-default-directory' is nil.)
-Fourth arg MUSTMATCH non-nil means require existing directory's name.
- Non-nil and non-t means also require confirmation after completion.
+
+If the user exits with an empty minibuffer, return an empty
+string.  (This can happen only if the user erased the pre-inserted
+contents or if `insert-default-directory' is nil.)
+
+Fourth arg MUSTMATCH, is like for `read-file-name', which see.
+
 Fifth arg INITIAL specifies text to start with.
-DIR should be an absolute directory name.  It defaults to
-the value of `default-directory'.
-When sixth arg PREDICATE is non-nil, the union of PREDICATE and
-`file-directory-p' is passed as the PREDICATE argument to
-`read-file-name'.  Otherwise, only `file-directory-p' is passed."
+
+Sixth arg PREDICATE, if non-nil, should be a function of one
+argument; then a directory is considered an acceptable completion
+alternative only if PREDICATE returns non-nil with the file name
+as its argument."
   (unless dir
     (setq dir default-directory))
   (read-file-name prompt dir (or default-dirname