From ded17e222eb17ce07439ceb770ded593419b0b37 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 13 Feb 2025 08:34:24 +0100 Subject: [PATCH] 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) --- lisp/files.el | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/lisp/files.el b/lisp/files.el index a3d5d526fba..e3f23231f5b 100644 --- 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 -- 2.39.5