[Emacs-diffs] emacs-25 b99a34b: Document 'directory-files-recursively'

[Eli Zaretskii]

branch: emacs-25
commit b99a34bcb030d59e0e272b3379d1725a6eb01d95
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/lispref/files.texi |   20 ++++++++++++++------
 etc/NEWS               |    7 ++++---
 lisp/files.el          |   16 +++++++++-------
 3 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 9a1b2cd..e8ed7cc 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
 
address@hidden directory-files-recursively directory match &optional 
include-directories
-Return all files under @var{directory} whose file names match
address@hidden 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 address@hidden,
-also return directory names that have matching names.
address@hidden 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 address@hidden, 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 b9e0bd4..bd7435b 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 e892ac6..f37c23b 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))))