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

[Eli Zaretskii]

> From: Clément Pit--Claudel <clement.pitclaudel@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.