[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attr
From: |
Eli Zaretskii |
Subject: |
Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' |
Date: |
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
> master:
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
prefer.
> +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
`file-attributes'
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...) ...)