From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Thu, 31 May 2018 11:51:45 +0000 (+0200)
Subject: Fdirectory_files_and_attributes doc string clarification
X-Git-Tag: emacs-27.0.90~4968
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=8ca42283939d458e30f74dce2bb1908257ea776f;p=emacs.git

Fdirectory_files_and_attributes doc string clarification

* src/dired.c (Fdirectory_files_and_attributes): Clarify what data
is returned.
---

diff --git a/src/dired.c b/src/dired.c
index c446223a0bc..115413dd6bc 100644
--- a/src/dired.c
+++ b/src/dired.c
@@ -358,6 +358,16 @@ If NOSORT is non-nil, the list is not sorted--its order is unpredictable.
 DEFUN ("directory-files-and-attributes", Fdirectory_files_and_attributes,
        Sdirectory_files_and_attributes, 1, 5, 0,
        doc: /* Return a list of names of files and their attributes in DIRECTORY.
+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 "/"))))
+
 There are four optional arguments:
 If FULL is non-nil, return absolute file names.  Otherwise return names
  that are relative to the specified directory.