doc: improve fs docs return value

doc/api/fs.md

@@ -186,7 +186,7 @@ added: v10.0.0
 * `data` {string|Buffer|TypedArray|DataView}
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
-* Returns: {Promise}
+* Returns: {Promise} Fulfills with `undefined` upon success.
 
 Alias of [`filehandle.writeFile()`][].
 
@@ -199,33 +199,31 @@ to with [`fsPromises.open()`][]. Therefore, this is equivalent to
 added: v10.0.0
 -->
 
-* `mode` {integer}
-* Returns: {Promise}
+* `mode` {integer} the file mode bit mask.
+* Returns: {Promise} Fulfills with `undefined` upon success.
 
-Modifies the permissions on the file. The promise is resolved with no
-arguments upon success.
+Modifies the permissions on the file. See chmod(2).
 
 #### `filehandle.chown(uid, gid)`
 <!-- YAML
 added: v10.0.0
 -->
 
-* `uid` {integer}
-* `gid` {integer}
-* Returns: {Promise}
+* `uid` {integer} The file's new owner's user id.
+* `gid` {integer}	* `gid` {integer} The file's new group's group id.
+* Returns: {Promise} Fulfills with `undefined` upon success.
 
-Changes the ownership of the file then resolves the promise with no arguments
-upon success.
+Changes the ownership of the file. A wrapper for chown(2).
 
 #### `filehandle.close()`
 <!-- YAML
 added: v10.0.0
 -->
 
-* Returns: {Promise}
+* Returns: {Promise} Fulfills with `undefined` upon success.
 
 Closes the file handle after waiting for any pending operation on the handle to
-complete. The promise is resolved with no arguments once complete.
+complete.
 
 ```js esm
 import { open } from 'fs/promises';
@@ -243,13 +241,13 @@ try {
 added: v10.0.0
 -->
 
-* Returns: {Promise}
+* Returns: {Promise} Fulfills with `undefined` upon success.
 
 Forces all currently queued I/O operations associated with the file to the
 operating system's synchronized I/O completion state. Refer to the POSIX
-fdatasync(2) documentation for details. The promise is resolved with no
-arguments upon success.
+fdatasync(2) documentation for details.
 
+Unlike `filehandle.sync` this method does not flush modified metadata.
 #### `filehandle.fd`
 <!-- YAML
 added: v10.0.0
@@ -271,16 +269,12 @@ added: v10.0.0
   file. If `null`, data will be read from the current file position, and
   the position will be updated. If `position` is an integer, the current
   file position will remain unchanged.
-* Returns: {Promise}
+* Returns: {Promise} Fulfills upon success with an object with two properties: 
+  * `bytesRead` {integer} The number of bytes read
+  * `buffer` {Buffer|Uint8Array} A reference to the passed in `buffer` argument.
 
 Reads data from the file and stores that in the given buffer.
 
-Following successful read, the promise is resolved with an object with
-two properties:
-
-* `bytesRead` {integer} The number of bytes read
-* `buffer` {Buffer|Uint8Array} A reference to the passed in `buffer` argument.
-
 If the file is not modified concurrently, the end-of-file is reached when the
 number of bytes read is zero.
 
@@ -300,16 +294,13 @@ added:
     file. If `null`, data will be read from the current file position, and
     the position will be updated. If `position` is an integer, the current
     file position will remain unchanged. **Default:**: `null`
-* Returns: {Promise}
+* Returns: {Promise} Fulfills upon success with an object with two properties:
+  * `bytesRead` {integer} The number of bytes read
+  * `buffer` {Buffer|Uint8Array} A reference to the passed in `buffer`
+  argument.
 
 Reads data from the file and stores that in the given buffer.
 
-Following successful read, the promise is resolved with an object with
-two properties:
-
-* `bytesRead` {integer} The number of bytes read
-* `buffer` {Buffer|Uint8Array} A reference to the passed in `buffer` argument.
-
 If the file is not modified concurrently, the end-of-file is reached when the
 number of bytes read is zero.
 
@@ -321,14 +312,12 @@ added: v10.0.0
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `null`
   * `signal` {AbortSignal} allows aborting an in-progress readFile
-* Returns: {Promise}
+* Returns: {Promise} Fulfills upon a successful read with the contents of the
+  file. If no encoding is specified (using `options.encoding`), the data is
+  returned as a {Buffer} object. Otherwise, the data will be a string.
 
 Asynchronously reads the entire contents of a file.
 
-The promise is resolved with the contents of the file. If no encoding is
-specified (using `options.encoding`), the data is returned as a {Buffer}
-object. Otherwise, the data will be a string.
-
 If `options` is a string, then it specifies the `encoding`.
 
 The {FileHandle} has to support reading.
@@ -349,16 +338,13 @@ added:
 * `position` {integer} The offset from the beginning of the file where the data
   should be read from. If `position` is not a `number`, the data will be read
   from the current position.
-* Returns: {Promise}
+* Returns: {Promise} Fulfills upon success an object containing two properties:
+  * `bytesRead` {integer} the number of bytes read
+  * `buffers` {Buffer[]|TypedArray[]|DataView[]} property containing
+    a reference to the `buffers` input.
 
 Read from a file and write to an array of {ArrayBufferView}s
 
-The promise is resolved with an object containing two properties:
-
-* `bytesRead` {integer} the number of bytes read
-* `buffers` {Buffer[]|TypedArray[]|DataView[]} property containing
-  a reference to the `buffers` input.
-
 #### `filehandle.stat([options])`
 <!-- YAML
 added: v10.0.0
@@ -372,32 +358,30 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
-* Returns: {Promise}
+* Returns: {Promise} Fulfills with an {fs.Stats} for the file.
+
 
-Resolves the promise with the {fs.Stats} for the file.
 
 #### `filehandle.sync()`
 <!-- YAML
 added: v10.0.0
 -->
 
-* Returns: {Promise}
+* Returns: {Promise} Fufills with `undefined` upon success.
 
 Request that all data for the open file descriptor is flushed to the storage
 device. The specific implementation is operating system and device specific.
 Refer to the POSIX fsync(2) documentation for more detail.
 
-The promise is resolved with no arguments upon success.
-
 #### `filehandle.truncate(len)`
 <!-- YAML
 added: v10.0.0
 -->
 
 * `len` {integer} **Default:** `0`
-* Returns: {Promise}
+* Returns: {Promise} Fulfills with `undefined` upo nsuccess.
 
-Truncates the file then resolves the promise with no arguments upon success.
+Truncates the file.
 
 If the file was larger than `len` bytes, only the first `len` bytes will be
 retained in the file.
@@ -2681,8 +2665,8 @@ changes:
 * `offset` {integer} The position in `buffer` to write the data to.
 * `length` {integer}  The number of bytes to read.
 * `position` {integer|bigint} Specifies where to begin reading from in the
-  file. If `position` is `null`, data will be read from the current file
-  position, and the file position will be updated. If `position` is an
+  file. If `position` is `null` or `-1 `, data will be read from the current
+  file position, and the file position will be updated. If `position` is an
   integer, the file position will be unchanged.
 * `callback` {Function}
   * `err` {Error}
@@ -4199,8 +4183,8 @@ added: v0.4.7
 -->
 
 * `fd` {integer}
-* `uid` {integer}
-* `gid` {integer}
+* `uid` {integer} The file's new owner's user id.
+* `gid` {integer}	* `gid` {integer} The file's new group's group id.
 
 Sets the owner of the file. Returns `undefined`.
 
@@ -4302,8 +4286,8 @@ changes:
 -->
 
 * `path` {string|Buffer|URL}
-* `uid` {integer}
-* `gid` {integer}
+* `uid` {integer} The file's new owner's user id.
+* `gid` {integer}	* `gid` {integer} The file's new group's group id.
 
 Set the owner for the path. Returns `undefined`.