From: Lars Ingebrigtsen <larsi@gnus.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes'
Date: Fri, 01 Jun 2018 15:20:35 +0200 [thread overview]
Message-ID: <m3o9guod7g.fsf@gnus.org> (raw)
In-Reply-To: <83h8mmfybh.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 01 Jun 2018 16:09:22 +0300")
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
prev parent reply other threads:[~2018-06-01 13:20 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20180601082809.7179.74843@vcs0.savannah.gnu.org>
[not found] ` <20180601082810.7BF3721297@vcs0.savannah.gnu.org>
2018-06-01 10:21 ` emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' Lars Ingebrigtsen
2018-06-01 12:10 ` Stefan Monnier
2018-06-01 13:09 ` Eli Zaretskii
2018-06-01 13:20 ` Lars Ingebrigtsen [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m3o9guod7g.fsf@gnus.org \
--to=larsi@gnus.org \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).