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: Eli Zaretskii <eliz <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#27798: closed (Documentation of locate-dominating-file is wrong)
Date: Fri, 28 Jul 2017 09:40:02 +0000

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

Your message dated Fri, 28 Jul 2017 12:39:10 +0300
with message-id <83d18k529t.fsf <at> gnu.org>
and subject line Re: bug#27798: Documentation of locate-dominating-file is wrong
has caused the debbugs.gnu.org bug report #27798,
regarding Documentation of locate-dominating-file is wrong
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> 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: 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 3 (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)]

[Message part 5 (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.

Previous Next

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