[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Lars Ingebrigtsen
Subject: Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'
Date: Fri, 01 Jun 2018 15:20:35 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux)

Eli Zaretskii <address@hidden> 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

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]