Document locate-dominating-file

* doc/lispref/files.texi (Contents of Directories): Document
locate-dominating-file (bug#33869).

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 3746c6d2c95e866a2d20e54540c7ce0addb16792..130282c582d6bdcf72da5d358d92730a2a77f7c5 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2924,6 +2924,7 @@ that can be read.
 @end defun
 
 @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
@@ -2949,6 +2950,19 @@ 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.
+@end defun
+
 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
 This is similar to @code{directory-files} in deciding which files
 to report on and how to report their names.  However, instead