Subject: bug#27798: closed (Re: bug#27798: Documentation of locate-dominating-file is wrong)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 28 Jul 2017 09:40:02 +0000

Your bug report

#27798: Documentation of locate-dominating-file is wrong

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
27798: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=27798
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#27798: Documentation of locate-dominating-file is wrong
From: Eli Zaretskii <[email-masked]>
To: Clément Pit--Claudel <[email-masked]>
Cc: [email-masked]
Date: Fri, 28 Jul 2017 12:39:10 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> Cc: [email-masked]
> From: Clément Pit--Claudel <[email-masked]>
> Date: Sun, 23 Jul 2017 18:08:23 +0200
> 
> On 2017-07-23 17:20, Eli Zaretskii wrote:
> > It would probably be more accurate if we said
> > 
> >   FILE can be a directory.
> 
> Sounds good.  In that case we also need to adjust the part of the docstring about NAME (when FILE is not a directory and NAME is a lambda, NAME is called with something that's not a directory — namely FILE).

Done.

Subject: Documentation of locate-dominating-file is wrong
From: Clément Pit--Claudel <[email-masked]>
To: [email-masked]
Date: Sun, 23 Jul 2017 11:49:36 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

The docs of locate-dominating-file say this:

  (locate-dominating-file FILE NAME)

  Look up the directory hierarchy from FILE for a directory containing NAME.
  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.

This part is wrong, because locate-dominating-file also accepts directories:

  Look up the directory hierarchy from FILE

This part is wrong, because the predicate is called with the initial file name, too:

  NAME can also be a predicate taking one argument (a directory)

Indeed, the following form:

  (locate-dominating-file "/usr/local/bin/emacs" (lambda (x) (ignore (message "%s" x))))

prints this:

  /usr/local/bin/emacs
  /usr/local/bin/
  /usr/local/
  /usr/
  /

(not the file name passed into the first call.

I think the fix is to update the docs in both places, as there might be callers relying on the existing behavior.  It's important to also document that passing a directory name is OK, though, because that's the only way to use locate-dominating-file reliably with a directory-only predicate — otherwise, the predicate needs to handle both files and folders.

Cheers,
Clément.