[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attr
Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'
Fri, 01 Jun 2018 16:09:22 +0300
> From: Lars Ingebrigtsen <address@hidden>
> Cc: Eli Zaretskii <address@hidden>
> Date: Fri, 01 Jun 2018 12:21:49 +0200
> address@hidden (Eli Zaretskii) writes:
> > +Value is a list of the form:
> > +
> > + ((FILE1 FILE1-ATTRS) (FILE2 FILE2-ATTRS) ...)
> > +
> > +where each FILEn-ATTRS is the attributes of FILEn as returned
> > +by `file-attributes'.
> Heh, I read the same reddit post, apparently, and fixed it like this on
Please always fix documentation issues on the release branch, not on
master. Unless they document features that are only available on
master, of course.
> +The list returned has elements that contain the data from
> +`file-attributes' for each file -- with the file name prepended. So
> +the structure of each element is
> +`(FILE-NAME FILE-ATTRIBUTE1 FILE-ATTRIBUTE2 ...)'.
I find "has elements that contain the data from `file-attributes' for
each file -- with the file name prepended" less clear than what I
wrote. YMMV, of course, and I'll let others tell which text they
> +For instance, to get the size of the fourth element in a directory,
> +you could say:
> + (file-attribute-size (cdr (nth 3 (directory-files-and-attributes "/"))))
That's redundant, I think; we never provide such "hints" anywhere else
where we describe lists being returned.
> Because (FILE1 FILE1-ATTRS) is a bit ambiguous, since it could mean
> ("file-name" (t 27 0 0 (23311 56666 366991 953000) (23220 586 761023 102000)
> (23220 586 761023 102000) 4096 "drwxr-xr-x" t 2 66306))
No, it cannot mean that, because the text says
where each FILEn-ATTRS is the attributes of FILEn as returned by
It doesn't say it's a list. If we think that's not clear enough we
can use this instead:
((FILE1 FILE1-ATTRS...) (FILE2 FILE2-ATTRS...) ...)