bug#4638: 23.1; doc string and Elisp manual descriptions of file-attributes

[Drew Adams]

>From the doc string:
 
 1. Number of links to file.
 
Please state that it is an integer value.
 
 2. File uid as a string or a number.  If a string value cannot be
    looked up, a numeric value, either an integer or a float, is
    returned.
 
Can we say how long the string is (fixed length or max)?
 
 10. inode number.  If inode number is larger than the Emacs integer...
 
Should presumably say "than the _largest_ Emacs integer".
 
Also, #10 contradicts what is said in the Elisp manual, node `File
Attributes'. Which is correct? The doc string speaks of a cons cell
containing possibly 3 integers. (And how can a single cons cell
contain 3 integers? Not clear.) The manual speaks of a (single) cons
cell with car and cdr integers.
 
 11. Device number.  If it is larger than the Emacs integer, this is
     a cons cell, similar to the inode number.
 
Again, it should presumably say _largest_ Emacs integer.
 
Also, it's not clear what "device number" means, and the Elisp manual
describes this differently, as "the file system number of the file
system that the file is in". Neither description is understandable,
but they especially do not seem to correspond, at least not in a
self-evident way. These desciptions need to be improved, at the very
least by referring to the original terminology (UNIX) or reference.
 
The following note is referenced only from #4, but #5 and #6 say
"likewise". The note speaks of "access time". It is not clear whether
the note applies only to #4 (access time) or also to #5 and #6. If it
applies only to #4, then it should just be moved to #4. Otherwise,
things should be rephrased to make clear what is meant (not
necessarily access time).
 
 On some FAT-based filesystems, only the date of last
 access is recorded, so last access time will always be
 midnight of that day.

It is important to get these descriptions right. How can we expect someone to
write code that depends on these values, if s?he cannot even know what forms
they can take?
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'