Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'

Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'

[Lars Ingebrigtsen]

eliz@gnu.org (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: 

+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 ...)'.
+
+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 "/"))))
+

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

instead of

("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)

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

Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'

[Stefan Monnier]

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

AFAIC, it's not ambiguous and the above is exactly what it means.
You can fix it with (FILE1 . FILE1-ATTRS) or (FILE1 FILE1-ATTRS...)


        Stefan

Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Fri, 01 Jun 2018 12:21:49 +0200
> 
> eliz@gnu.org (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...) ...)

Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

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

I think the Emacs doc strings could do with more code examples in
general...

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

As long as it's clear to the user that they have to say `cdr' to get to
the attributes instead of `cadr', that's fine (and is pretty much what I
did in my version).

I mean, this is a very simple function, but describing what the user has
to do to get to the values is surprisingly difficult due to the
non-opacity of the data structures here.

And sorry for not doing the doc fix on the emacs-26 branch instead of
master; I should know better.

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