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.

1 files changed, 14 insertions, 6 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