Document 'directory-files-recursively'

* lisp/files.el (directory-files-recursively): Doc fix.  Rename
the argument MATCH to REGEXP, to be more explicit about its form.

* doc/lispref/files.texi (Contents of Directories): Improve the
documentation of 'directory-files-recursively'.  Add
cross-references.

* etc/NEWS: Move the entry for 'directory-files-recursively' to
its place and mark it documented.

3 files changed, 27 insertions, 16 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 9a1b2cd217f..e8ed7ccd9f7 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2632,12 +2632,20 @@ An error is signaled if @var{directory} is not the name of a directory
 that can be read.
 @end defun
 
-@defun directory-files-recursively directory match &optional include-directories
-Return all files under @var{directory} whose file names match
-@var{match} recursively.  The file names are returned depth first,
-meaning that contents of sub-directories are returned before contents
-of the directories.  If @var{include-directories} is non-@code{nil},
-also return directory names that have matching names.
+@defun directory-files-recursively directory regexp &optional include-directories
+Return all files under @var{directory} whose names match @var{regexp}.
+This function searches the specified @var{directory} and its
+sub-directories, recursively, for files whose basenames (i.e., without
+the leading directories) match the specified @var{regexp}, and returns
+a list of the absolute file names of the matching files
+(@pxref{Relative File Names, absolute file names}).  The file names
+are returned in depth-first order, meaning that files in some
+sub-directory are returned before the files in its parent directory.
+In addition, matching files found in each subdirectory are sorted
+alphabetically by their basenames.  By default, directories whose
+names match @var{regexp} are omitted from the list, but if the
+optional argument @var{include-directories} is non-@code{nil}, they
+are included.
 @end defun
 
 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
diff --git a/etc/NEWS b/etc/NEWS
index b9e0bd4ba24..bd7435b1760 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -181,9 +181,6 @@ for use in Emacs bug reports.
 hiding character but the default `.' can be used by let-binding the
 variable `read-hide-char'.
 
-** A new function `directory-files-recursively' returns all matching
-files (recursively) under a directory.
-
 ** The new function `directory-name-p' can be used to check whether a file
 name (as returned from, for instance, `file-name-all-completions' is
 a directory file name.  It returns non-nil if the last character in
@@ -1138,6 +1135,10 @@ process filter, sentinel, etc., through keyword arguments (similar to
 `make-network-process').
 
 +++
+** A new function `directory-files-recursively' returns all matching
+files (recursively) under a directory.
+
++++
 ** New variable `inhibit-message', when bound to non-nil, inhibits
 `message' and related functions from displaying messages the Echo
 Area.  The output is still logged to the *Messages* buffer.
diff --git a/lisp/files.el b/lisp/files.el
index e892ac6b94b..f37c23b7bdd 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -744,11 +744,13 @@ The path separator is colon in GNU and GNU-like systems."
   (and (> (length name) 0)
        (char-equal (aref name (1- (length name))) ?/)))
 
-(defun directory-files-recursively (dir match &optional include-directories)
-  "Return all files under DIR that have file names matching MATCH (a regexp).
+(defun directory-files-recursively (dir regexp &optional include-directories)
+  "Return list of all files under DIR that have file names matching REGEXP.
 This function works recursively.  Files are returned in \"depth first\"
-and alphabetical order.
-If INCLUDE-DIRECTORIES, also include directories that have matching names."
+order, and files from each directory are sorted in alphabetical order.
+Each file name appears in the returned list in its absolute form.
+Optional argument INCLUDE-DIRECTORIES non-nil means also include in the
+output directories whose names match REGEXP."
   (let ((result nil)
         (files nil)
         ;; When DIR is "/", remote file names like "/method:" could
@@ -764,11 +766,11 @@ If INCLUDE-DIRECTORIES, also include directories that have matching names."
               (unless (file-symlink-p full-file)
                 (setq result
                       (nconc result (directory-files-recursively
-                                     full-file match include-directories))))
+                                     full-file regexp include-directories))))
               (when (and include-directories
-                         (string-match match leaf))
+                         (string-match regexp leaf))
                 (setq result (nconc result (list full-file)))))
-          (when (string-match match file)
+          (when (string-match regexp file)
             (push (expand-file-name file dir) files)))))
     (nconc result (nreverse files))))