1 files changed, 17 insertions, 11 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 130282c582d..32297e98758 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2923,8 +2923,8 @@ An error is signaled if @var{directory} is not the name of a directory
 that can be read.
 @end defun
 
+@cindex recursive traverse of directory tree
 @defun directory-files-recursively directory regexp &optional include-directories predicate follow-symlinks
-@cindex recursing downwards in 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
@@ -2950,17 +2950,23 @@ Symbolic links to subdirectories are not followed by default, but if
 @var{follow-symlinks} is non-@code{nil}, they are followed.
 @end defun
 
+
 @defun locate-dominating-file file name
-@cindex recursing upwards in directories
-Starting at @var{file}, recurse up the directory hierarchy looking for
-the first directory where @var{name} exists, which is then the return
-value of this function.  @var{file} can be a file or a directory.  If
-it's a file, its directory will serve as the starting point for
-searching the hierarchy of directories.
-
-@code{name} can be either a string or a predicate.  The predicate
-takes one argument (the directory) and should return non-@code{nil} if
-we've found the directory we're looking for.
+Starting at @var{file}, go up the directory tree hierarchy looking for
+the first directory where @var{name}, a string, exists, and return that
+directory.  If @var{file} is a file, its directory will serve as the
+starting point for the search; otherwise @var{file} should be a
+directory from which to start.  The function looks in the starting
+directory, then in its parent, then in its parent's parent, etc.,
+until it either finds a directory with @var{name} or reaches the root
+directory of the filesystem without finding @var{name} -- in the
+latter case the function returns @code{nil}.
+
+The argument @code{name} can also be a predicate function.  The
+predicate is called for every directory examined by the function,
+starting from @var{file} (even if @var{file} is not a directory).  It
+is called with one argument (the file or directory) and should return
+non-@code{nil} if that directory is the one it is looking for.
 @end defun
 
 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format