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

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

[Drew Adams]

The doc should distinguish between the files _within_ a directory, i.e.,
descending into its subdirectories recursively, and the files in a
directory, i.e., not including in descendent directories.

Pick any terminology you like, but please make it clear.  

1. `find-listp-find-files': The doc of does not at all indicate that it
in fact searches also subdirectories, recursively.

2. `find-lisp-find-files-internal': The doc says that
"DIRECTORY-PREDICATE is used to decide...", but it does not say how,
which is central to the meaning of DIRECTORY-PREDICATE.  Just say that
if DIRECTORY-PREDICATE returns non-nil then descend into subdirs etc.

3. `find-lisp-find-dired-internal': The doc says "Run find...".
Please change this to "Run `find'...".

4. `find-lisp-find-dired-filter': Please replace the doc string with
something correct or useful.  The command does not "change the
filter..." or anything of the kind.  And please wrap function names with
`...' in doc.

5. `find-lisp-format': Add a doc string.  You "lifted" this from
ls-lisp.el, but you neglected to lift the doc string along with it.

6. `find-lisp-time-index', `find-lisp-format-time': Replace the code
comments with doc strings.  This is the 21st century; we can afford
the extra cost. ;-)

7. `find-lisp-find-dired-insert-file': Add a doc string.



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-02 on ODIEONE
Bzr revision: 113660 lekktu@gmail.com-20130802160313-rbi3o6322mz0m3ye
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

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

[Lars Ingebrigtsen]

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

> The doc should distinguish between the files _within_ a directory, i.e.,
> descending into its subdirectories recursively, and the files in a
> directory, i.e., not including in descendent directories.
>
> Pick any terminology you like, but please make it clear.  
>
> 1. `find-listp-find-files': The doc of does not at all indicate that it
> in fact searches also subdirectories, recursively.

Fixed...

> 2. `find-lisp-find-files-internal': The doc says that
> "DIRECTORY-PREDICATE is used to decide...", but it does not say how,
> which is central to the meaning of DIRECTORY-PREDICATE.  Just say that
> if DIRECTORY-PREDICATE returns non-nil then descend into subdirs etc.

It's a predicate.  That's what predicates do.

> 3. `find-lisp-find-dired-internal': The doc says "Run find...".
> Please change this to "Run `find'...".

But it doesn't run the command `find'.  And it says:

  "Run find (Lisp version) and go into Dired mode on a buffer of the output."

> 4. `find-lisp-find-dired-filter': Please replace the doc string with
> something correct or useful.  The command does not "change the
> filter..." or anything of the kind.  And please wrap function names with
> `...' in doc.

But it does change the filter...

;;;###autoload
(defun find-lisp-find-dired-filter (regexp)
  "Change the filter on a `find-lisp-find-dired' buffer to REGEXP."
  (interactive "sSet filter to regexp: ")
  (setq find-lisp-regexp regexp)
  (revert-buffer))

And I see that Juanma has already fixed the quoting...

> 5. `find-lisp-format': Add a doc string.  You "lifted" this from
> ls-lisp.el, but you neglected to lift the doc string along with it.

Done.

> 6. `find-lisp-time-index', `find-lisp-format-time': Replace the code
> comments with doc strings.  This is the 21st century; we can afford
> the extra cost. ;-)

Done.

> 7. `find-lisp-find-dired-insert-file': Add a doc string.

Seems unnecessary.

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

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

[Drew Adams]

> > The doc should distinguish between the files _within_ a directory, i.e.,
> > descending into its subdirectories recursively, and the files in a
> > directory, i.e., not including in descendent directories.
> >
> > Pick any terminology you like, but please make it clear.
> >
> > 1. `find-listp-find-files': The doc of does not at all indicate that it
> > in fact searches also subdirectories, recursively.
> 
> Fixed...
> 
> > 2. `find-lisp-find-files-internal': The doc says that
> > "DIRECTORY-PREDICATE is used to decide...", but it does not say how,
> > which is central to the meaning of DIRECTORY-PREDICATE.  Just say that
> > if DIRECTORY-PREDICATE returns non-nil then descend into subdirs etc.
> 
> 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.

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

[Michael Heerdegen]

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.

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

[Drew Adams]

> "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.

OK.

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

"Whether" does not imply that non-nil (aka "yes") means descend.
It can just as easily mean do not descend.  Yes, it's a predicate,
and yes, whether to descend is decided based on the return value.
But which return value means descend?  "Whether" tells you no
more than "predicate" or "if".

Admittedly, this is not very important.  Still, if we are going
to spend time and energy talking about this, we might as well
make it right.

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

[Eli Zaretskii]

> Date: Sun, 1 May 2016 06:28:04 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 15047@debbugs.gnu.org
> 
> > "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.
> 
> OK.
> 
> > 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...
> 
> "Whether" does not imply that non-nil (aka "yes") means descend.

I think you are the only one who could ever imagine such a meaning of
that sentence.

> Admittedly, this is not very important.  Still, if we are going
> to spend time and energy talking about this, we might as well
> make it right.

Or we might stop wasting time splitting hair.