docs: improved fs.Stats section in API documentation

doc/api/fs.markdown

@@ -133,23 +133,8 @@ Synchronous lchmod(2).
 ### fs.stat(path, [callback])
 
 Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
-`stats` is a [`fs.Stats`](#fs.Stats) object. It looks like this:
+`stats` is a [`fs.Stats`](#fs.Stats) object.  See the [fs.Stats](#fs.Stats)
-
+section below for more information.
-    { dev: 2049,
-      ino: 305352,
-      mode: 16877,
-      nlink: 12,
-      uid: 1000,
-      gid: 1000,
-      rdev: 0,
-      size: 4096,
-      blksize: 4096,
-      blocks: 8,
-      atime: '2009-06-29T11:11:55Z',
-      mtime: '2009-06-29T11:11:40Z',
-      ctime: '2009-06-29T11:11:40Z' }
-
-See the [fs.Stats](#fs.Stats) section below for more information.
 
 ### fs.lstat(path, [callback])
 
@@ -266,7 +251,7 @@ Asynchronous file open. See open(2). `flags` can be:
 * `'r'` - Open file for reading.
 An exception occurs if the file does not exist.
 
-* `'r+'` - Open file for reading and writing. 
+* `'r+'` - Open file for reading and writing.
 An exception occurs if the file does not exist.
 
 * `'w'` - Open file for writing.
@@ -457,7 +442,8 @@ callback, and have some fallback logic if it is null.
 
 ## fs.Stats
 
-Objects returned from `fs.stat()` and `fs.lstat()` are of this type.
+Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their
+synchronous counterparts are of this type.
 
  - `stats.isFile()`
  - `stats.isDirectory()`
@@ -467,6 +453,35 @@ Objects returned from `fs.stat()` and `fs.lstat()` are of this type.
  - `stats.isFIFO()`
  - `stats.isSocket()`
 
+For a regular file `sys.inspect(stats)` would return a string very
+similar to this:
+
+    { dev: 2114,
+      ino: 48064969,
+      mode: 33188,
+      nlink: 1,
+      uid: 85,
+      gid: 100,
+      rdev: 0,
+      size: 527,
+      blksize: 4096,
+      blocks: 8,
+      atime: Mon, 10 Oct 2011 23:24:11 GMT,
+      mtime: Mon, 10 Oct 2011 23:24:11 GMT,
+      ctime: Mon, 10 Oct 2011 23:24:11 GMT }
+
+Please note that `atime`, `mtime` and `ctime` are instances
+of [`Date`][MDN-Date] object and to compare the values of
+these objects you should use appropriate methods. For most
+general uses [`getTime()`][MDN-Date-getTime] will return
+the number of milliseconds elapsed since _1 January 1970
+00:00:00 UTC_ and this integer should be sufficient for
+any comparison, however there additional methods which can
+be used for displaying fuzzy information. More details can
+be found in the [MDN JavaScript Reference][MDN-Date] page.
+
+[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
+[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
 
 ## fs.ReadStream