From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 28 Jul 2017 09:35:36 +0000 (+0300)
Subject: Improve doc string of 'locate-dominating-file'
X-Git-Tag: emacs-26.0.90~517^2~88
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=82c7c1e4394ec160fe67134659c9c662760d31e2;p=emacs.git

Improve doc string of 'locate-dominating-file'

* lisp/files.el (locate-dominating-file): Doc fix.  (Bug#27798)
---

diff --git a/lisp/files.el b/lisp/files.el
index 321a35b530d..6d9957d494a 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -978,12 +978,15 @@ or mount points potentially requiring authentication as a different user.")
 ;;       nil)))
 
 (defun locate-dominating-file (file name)
-  "Look up the directory hierarchy from FILE for a directory containing NAME.
+  "Starting from FILE, look up directory hierarchy for directory containing NAME.
+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.
 Stop at the first parent directory containing a file NAME,
 and return the directory.  Return nil if not found.
 Instead of a string, NAME can also be a predicate taking one argument
 \(a directory) and returning a non-nil value if that directory is the one for
-which we're looking."
+which we're looking.  The predicate will be called with every file/directory
+the function needs to examine, starting with FILE."
   ;; We used to use the above locate-dominating-files code, but the
   ;; directory-files call is very costly, so we're much better off doing
   ;; multiple calls using the code in here.