GNU bug report logs - #27798
Documentation of locate-dominating-file is wrong

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Clément Pit--Claudel <clement.pitclaudel <at> live.com>
Subject: bug#27798: closed (Re: bug#27798: Documentation of
 locate-dominating-file is wrong)
Date: Fri, 28 Jul 2017 09:40:02 +0000

[Message part 1 (text/plain, inline)]

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 27798 <at> debbugs.gnu.org.

-- 
27798: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=27798
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Clément Pit--Claudel <clement.pitclaudel <at> live.com>
Cc: 27798-done <at> debbugs.gnu.org
Subject: Re: bug#27798: Documentation of locate-dominating-file is wrong
Date: Fri, 28 Jul 2017 12:39:10 +0300

> Cc: 27798 <at> debbugs.gnu.org
> From: Clément Pit--Claudel <clement.pitclaudel <at> live.com>
> 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.

[Message part 3 (message/rfc822, inline)]

From: Clément Pit--Claudel <clement.pitclaudel <at> live.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Documentation of locate-dominating-file is wrong
Date: Sun, 23 Jul 2017 11:49:36 +0200

[Message part 4 (text/plain, inline)]

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.

[signature.asc (application/pgp-signature, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.