bug#15047: 24.3.50; doc string of `find-listp-find-files' etc.

[Michael Heerdegen <michael_heerdegen@web.de>]

Drew Adams <drew.adams@oracle.com> writes:

> > It's a predicate.  That's what predicates do.
>
> Have you looked at this doc and function?
>
> I had no complaint with what the doc string says about arg
> FILE-PREDICATE.  It says that it is a predicate that files
> under DIRECTORY need to satisfy, for them to be found.
>
> Things are very different for DIRECTORY-PREDICATE.  What is
> it?  What is it applied to?  If you look at the code you will
> see that it is applied to a directory, and if it succeeds
> the function is called recursively to look for files under
> that directory.
>
> That should be explained in the doc: what the predicate is
> applied to and what its effect is.

The doc says:

"DIRECTORY-PREDICATE is used to decide whether to descend into
directories.  It is a function which takes two arguments, the directory
and its parent."

I think with this wording its obvious what DIRECTORY-PREDICATE it is
applied to.

I also think the word "whether" suggests how the boolean return value is
interpreted: descent when the predicate returns non-nil (aka "yes").
We could say that explicitly, sure, but I think it's worth it...


Michael.