bug#33869: 26.1; function locate-dominating-file not documented in elisp manual

bug#33869: 26.1; function locate-dominating-file not documented in elisp manual

[Adam Porter]

The function locate-dominating-file appears to be missing from the elisp
manual.  Interestingly, this was noticed and asked by another user on
another forum:

https://stackoverflow.com/questions/40618516/where-is-locate-dominating-file-documented

I noticed this because just now I was trying to remember the name of the
function, and I kept looking in apropos and the manual for other words
and word lists like "overriding", "find file", "find path", "find
directory", etc.

I finally found it by searching Google for "emacs function find repo
directory", and the second hit was a question on Emacs.StackExchange
that mentioned locate-dominating-file.

Thanks.

bug#33869: 26.1; function locate-dominating-file not documented in elisp manual

[Eli Zaretskii]

> From: Adam Porter <adam@alphapapa.net>
> Date: Tue, 25 Dec 2018 14:23:51 -0600
> 
> The function locate-dominating-file appears to be missing from the elisp
> manual.  Interestingly, this was noticed and asked by another user on
> another forum:
> 
> https://stackoverflow.com/questions/40618516/where-is-locate-dominating-file-documented
> 
> I noticed this because just now I was trying to remember the name of the
> function, and I kept looking in apropos and the manual for other words
> and word lists like "overriding", "find file", "find path", "find
> directory", etc.

If we cannot come up with a phrase or a list of phrases for which
locate-dominating-file might be the hit one looks for, I don't see how
adding this to the ELisp manual could improve the discoverability.
None of those you tried above sound right to me, and I'm hard-pressed
for coming with something that is right.  The guy in the SO discussion
wanted the root of the VC repository, which is just one special case
where this function can help, and happens to have a better answer
(vc-root-dir).  So that discussion doesn't really help.

Thus, please suggest phrases that could serve as index entries for
this function.

> I finally found it by searching Google for "emacs function find repo
> directory", and the second hit was a question on Emacs.StackExchange
> that mentioned locate-dominating-file.

When I try that search, only the first hit is a StackExchange
discussion, and it doesn't mention this function.  What am I missing?

Thanks.

bug#33869: 26.1; function locate-dominating-file not documented in elisp manual

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> The function locate-dominating-file appears to be missing from the elisp
>> manual. 

[...]

> If we cannot come up with a phrase or a list of phrases for which
> locate-dominating-file might be the hit one looks for, I don't see how
> adding this to the ELisp manual could improve the discoverability.

I've now documented it right below directory-files-recursively and
cindexed them both with (respectively)

@cindex recursing upwards in directories

@cindex recursing downwards in directories

since they are kinda opposites of each other.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no