* bug#15047: 24.3.50; doc string of `find-listp-find-files' etc.
@ 2013-08-07 22:06 Drew Adams
2016-04-29 13:36 ` Lars Ingebrigtsen
0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2013-08-07 22:06 UTC (permalink / raw)
To: 15047
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'
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#15047: 24.3.50; doc string of `find-listp-find-files' etc.
2013-08-07 22:06 bug#15047: 24.3.50; doc string of `find-listp-find-files' etc Drew Adams
@ 2016-04-29 13:36 ` Lars Ingebrigtsen
2016-04-29 17:19 ` Drew Adams
0 siblings, 1 reply; 6+ messages in thread
From: Lars Ingebrigtsen @ 2016-04-29 13:36 UTC (permalink / raw)
To: Drew Adams; +Cc: 15047
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#15047: 24.3.50; doc string of `find-listp-find-files' etc.
2016-04-29 13:36 ` Lars Ingebrigtsen
@ 2016-04-29 17:19 ` Drew Adams
2016-05-01 13:46 ` Michael Heerdegen
0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2016-04-29 17:19 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 15047
> > 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#15047: 24.3.50; doc string of `find-listp-find-files' etc.
2016-04-29 17:19 ` Drew Adams
@ 2016-05-01 13:46 ` Michael Heerdegen
2016-05-01 14:28 ` Drew Adams
0 siblings, 1 reply; 6+ messages in thread
From: Michael Heerdegen @ 2016-05-01 13:46 UTC (permalink / raw)
To: Drew Adams; +Cc: Lars Ingebrigtsen, 15047
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#15047: 24.3.50; doc string of `find-listp-find-files' etc.
2016-05-01 13:46 ` Michael Heerdegen
@ 2016-05-01 14:28 ` Drew Adams
2016-05-01 15:12 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2016-05-01 14:28 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: Lars Ingebrigtsen, 15047
> "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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#15047: 24.3.50; doc string of `find-listp-find-files' etc.
2016-05-01 14:28 ` Drew Adams
@ 2016-05-01 15:12 ` Eli Zaretskii
0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2016-05-01 15:12 UTC (permalink / raw)
To: Drew Adams; +Cc: michael_heerdegen, larsi, 15047
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-05-01 15:12 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-08-07 22:06 bug#15047: 24.3.50; doc string of `find-listp-find-files' etc Drew Adams
2016-04-29 13:36 ` Lars Ingebrigtsen
2016-04-29 17:19 ` Drew Adams
2016-05-01 13:46 ` Michael Heerdegen
2016-05-01 14:28 ` Drew Adams
2016-05-01 15:12 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).