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

Previous Next

Full log

Message #8 received at 27798 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Clément Pit--Claudel <clement.pitclaudel <at> live.com>
Cc: 27798 <at> debbugs.gnu.org
Subject: Re: bug#27798: Documentation of locate-dominating-file is wrong
Date: Sun, 23 Jul 2017 17:31:51 +0300

> From: Clément Pit--Claudel <clement.pitclaudel <at> live.com>
> Date: Sun, 23 Jul 2017 11:49:36 +0200
> 
>   (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

Actually, FILE _must_ be a directory, because the function does this:

      (setq try (if (stringp name)
                    (file-exists-p (expand-file-name name file))
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^

It's possible that "directory hierarchy from FILE" doesn't convey that
clearly enough, in which case we could add

  FILE should be a directory.

> 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)

Why you say that this is wrong?  The doc string never said anything to
the contrary.

If we change the first sentence to say this:

  Starting from FILE, look up directory hierarchy for directory containing NAME.

will that address the second issue?

Thanks.

Previous Next

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