doc: unify and compact some fragments in fs.md

PR-URL: https://github.com/nodejs/node/pull/20050
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

2 files changed, 25 insertions, 51 deletions

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 63c07566c8..69138b6ac4 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1298,35 +1298,20 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
-  * `flags` {string}
-  * `encoding` {string}
-  * `fd` {integer}
-  * `mode` {integer}
-  * `autoClose` {boolean}
+  * `flags` {string} **Default:** `'r'`
+  * `encoding` {string} **Default:** `null`
+  * `fd` {integer} **Default:** `null`
+  * `mode` {integer} **Default:** `0o666`
+  * `autoClose` {boolean} **Default:** `true`
   * `start` {integer}
-  * `end` {integer}
-  * `highWaterMark` {integer}
-* Returns: {stream.Readable}
-
-Returns a new [`ReadStream`][] object. (See [Readable Streams][]).
+  * `end` {integer} **Default:** `Infinity`
+  * `highWaterMark` {integer} **Default:** `64 * 1024`
+* Returns: {fs.ReadStream} See [Readable Streams][].
 
 Be aware that, unlike the default value set for `highWaterMark` on a
 readable stream (16 kb), the stream returned by this method has a
 default value of 64 kb for the same parameter.
 
-`options` is an object or string with the following defaults:
-
-```js
-const defaults = {
-  flags: 'r',
-  encoding: null,
-  fd: null,
-  mode: 0o666,
-  autoClose: true,
-  highWaterMark: 64 * 1024
-};
-```
-
 `options` can include `start` and `end` values to read a range of bytes from
 the file instead of the entire file. Both `start` and `end` are inclusive and
 start counting at 0. If `fd` is specified and `start` is omitted or `undefined`,
@@ -1376,27 +1361,13 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
-  * `flags` {string}
-  * `encoding` {string}
-  * `fd` {integer}
-  * `mode` {integer}
-  * `autoClose` {boolean}
+  * `flags` {string} **Default:** `'w'`
+  * `encoding` {string} **Default:** `'utf8'`
+  * `fd` {integer} **Default:** `null`
+  * `mode` {integer} **Default:** `0o666`
+  * `autoClose` {boolean} **Default:** `true`
   * `start` {integer}
-* Returns: {stream.Writable}
-
-Returns a new [`WriteStream`][] object. (See [Writable Stream][]).
-
-`options` is an object or string with the following defaults:
-
-```js
-const defaults = {
-  flags: 'w',
-  encoding: 'utf8',
-  fd: null,
-  mode: 0o666,
-  autoClose: true
-};
-```
+* Returns: {fs.WriteStream} See [Writable Stream][].
 
 `options` may also include a `start` option to allow writing data at
 some position past the beginning of the file. Modifying a file rather
@@ -1410,7 +1381,7 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
-Like [`ReadStream`][], if `fd` is specified, `WriteStream` will ignore the
+Like [`ReadStream`][], if `fd` is specified, [`WriteStream`][] will ignore the
 `path` argument and will use the specified file descriptor. This means that no
 `'open'` event will be emitted. Note that `fd` should be blocking; non-blocking
 `fd`s should be passed to [`net.Socket`][].
@@ -1675,7 +1646,7 @@ added: v0.1.95
 * `fd` {integer}
 * Returns: {fs.Stats}
 
-Synchronous fstat(2). Returns an instance of [`fs.Stats`][].
+Synchronous fstat(2).
 
 ## fs.fsync(fd, callback)
 <!-- YAML
@@ -1978,7 +1949,7 @@ changes:
 * `path` {string|Buffer|URL}
 * Returns: {fs.Stats}
 
-Synchronous lstat(2). Returns an instance of [`fs.Stats`][].
+Synchronous lstat(2).
 
 ## fs.mkdir(path[, mode], callback)
 <!-- YAML
@@ -2339,10 +2310,9 @@ changes:
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
-* Returns: {string[]} An array of filenames
+* Returns: {string[]} An array of filenames excluding `'.'` and `'..'`.
 
-Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
-`'..'`.
+Synchronous readdir(3).
 
 The optional `options` argument can be a string specifying an encoding, or an
 object with an `encoding` property specifying the character encoding to use for
@@ -2841,7 +2811,7 @@ changes:
 * `path` {string|Buffer|URL}
 * Returns: {fs.Stats}
 
-Synchronous stat(2). Returns an instance of [`fs.Stats`][].
+Synchronous stat(2).
 
 ## fs.symlink(target, path[, type], callback)
 <!-- YAML
@@ -3094,9 +3064,10 @@ changes:
 * `listener` {Function|undefined} **Default:** `undefined`
   * `eventType` {string}
   * `filename` {string|Buffer}
+* Returns: {fs.FSWatcher}
 
 Watch for changes on `filename`, where `filename` is either a file or a
-directory. The returned object is a [`fs.FSWatcher`][].
+directory.
 
 The second argument is optional. If `options` is provided as a string, it
 specifies the `encoding`. Otherwise `options` should be passed as an object.
diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js
index 134df2b441..55998d1c22 100644
--- a/tools/doc/type-parser.js
+++ b/tools/doc/type-parser.js
@@ -59,7 +59,10 @@ const customTypesMap = {
   'EventEmitter': 'events.html#events_class_eventemitter',
 
   'FileHandle': 'fs.html#fs_class_filehandle',
+  'fs.FSWatcher': 'fs.html#fs_class_fs_fswatcher',
+  'fs.ReadStream': 'fs.html#fs_class_fs_readstream',
   'fs.Stats': 'fs.html#fs_class_fs_stats',
+  'fs.WriteStream': 'fs.html#fs_class_fs_writestream',
 
   'http.Agent': 'http.html#http_class_http_agent',
   'http.ClientRequest': 'http.html#http_class_http_clientrequest',