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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 23 Jul 2017 18:20:20 +0300

> Cc: [email-masked]
> From: Clément Pit--Claudel <[email-masked]>
> Date: Sun, 23 Jul 2017 16:52:51 +0200
> 
> > Actually, FILE _must_ be a directory, because the function does this:
> > 
> >       (setq try (if (stringp name)
> >                     (file-exists-p (expand-file-name name file))
> >                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> Ouch.  This is a problem, because I'm not the only one who assumed that this had to be a file and not a directory.  There are instances of locate-dominating-file being called with file-name in vc, trampver, yasnippet, company, flycheck, proof-general, etc.  Github finds 35k matches for (locate-dominating-file buffer-file-name) (https://github.com/search?q=%28locate-dominating-file+buffer-file-name&type=Code&utf8=%E2%9C%93).

buffer-file-name could be a directory, couldn't it?

But anyway, calling this function with a non-directory file just
wastes one iteration through the loop, so perhaps the situation is not
as bad as my original response made it sound.

> > 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.
> 
> Yes, this would be great.

It would probably be more accurate if we said

  FILE can be a directory.