From ec56cbe572f55dc055d96c8cde6ebd0958aedcda Mon Sep 17 00:00:00 2001
From: Refael Ackermann <refack@gmail.com>
Date: Mon, 10 Jul 2017 10:53:50 -0400
Subject: [PATCH] doc: improve fs.utimes

PR-URL: https://github.com/nodejs/node/pull/14154
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
---
 doc/api/fs.md | 27 ++++++++++++---------------
 1 file changed, 12 insertions(+), 15 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index dbeb835755d79f..934c392fa8ddb3 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1323,13 +1323,13 @@ changes:
 -->
 
 * `fd` {integer}
-* `atime` {integer}
-* `mtime` {integer}
+* `atime` {number|string|Date}
+* `mtime` {number|string|Date}
 * `callback` {Function}
   * `err` {Error}
 
-Change the file timestamps of a file referenced by the supplied file
-descriptor.
+Change the file system timestamps of the object referenced by the supplied file
+descriptor. See [`fs.utimes()`][].
 
 *Note*: This function does not work on AIX versions before 7.1, it will return
 the error `UV_ENOSYS`.
@@ -2354,21 +2354,18 @@ changes:
 -->
 
 * `path` {string|Buffer|URL}
-* `atime` {integer}
-* `mtime` {integer}
+* `atime` {number|string|Date}
+* `mtime` {number|string|Date}
 * `callback` {Function}
   * `err` {Error}
 
-Change file timestamps of the file referenced by the supplied path.
-
-*Note*: The arguments `atime` and `mtime` of the following related functions
-follow these rules:
+Change the file system timestamps of the object referenced by `path`.
 
-- The value should be a Unix timestamp in seconds. For example, `Date.now()`
-  returns milliseconds, so it should be divided by 1000 before passing it in.
-- If the value is a numeric string like `'123456789'`, the value will get
-  converted to the corresponding number.
-- If the value is `NaN`, `Infinity` or `-Infinity`, an Error will be thrown.
+The `atime` and `mtime` arguments follow these rules:
+- Values can be either numbers representing Unix epoch time, `Date`s, or a
+  numeric string like `'123456789.0'`.
+- If the value can not be converted to a number, or is `NaN`, `Infinity` or
+  `-Infinity`, a `Error` will be thrown.
 
 ## fs.utimesSync(path, atime, mtime)
 <!-- YAML