From 10f296f50d96b0251b4cba8f9d8f03f16cd9be3d Mon Sep 17 00:00:00 2001
From: Livia Medeiros <74449973+LiviaMedeiros@users.noreply.github.com>
Date: Tue, 3 May 2022 01:40:30 +0800
Subject: [PATCH] doc: clarify some default values in `fs.md`

PR-URL: https://github.com/nodejs/node/pull/42892
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Akhil Marsonya <akhil.marsonya27@gmail.com>
---
 doc/api/fs.md | 66 +++++++++++++++++++++++++--------------------------
 lib/fs.js     | 20 ++++++++--------
 2 files changed, 43 insertions(+), 43 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index c360c7a35e1921..27a4f2e9739630 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -374,7 +374,7 @@ added: v10.0.0
   file data read.
 * `offset` {integer} The location in the buffer at which to start filling.
 * `length` {integer} The number of bytes to read.
-* `position` {integer} The location where to begin reading data from the
+* `position` {integer|null} The location where to begin reading data from the
   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.
@@ -403,7 +403,7 @@ added:
     **Default:** `0`
   * `length` {integer} The number of bytes to read. **Default:**
     `buffer.byteLength - offset`
-  * `position` {integer} The location where to begin reading data from the
+  * `position` {integer|null} The location where to begin reading data from the
     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`
@@ -450,9 +450,9 @@ added:
 -->
 
 * `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
-* `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.
+* `position` {integer|null} 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. **Default:** `null`
 * Returns: {Promise} Fulfills upon success an object containing two properties:
   * `bytesRead` {integer} the number of bytes read
   * `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} property containing
@@ -550,10 +550,10 @@ changes:
   to write begins. **Default:** `0`
 * `length` {integer} The number of bytes from `buffer` to write. **Default:**
   `buffer.byteLength - offset`
-* `position` {integer} The offset from the beginning of the file where the
+* `position` {integer|null} The offset from the beginning of the file where the
   data from `buffer` should be written. If `position` is not a `number`,
   the data will be written at the current position. See the POSIX pwrite(2)
-  documentation for more detail.
+  documentation for more detail. **Default:** `null`
 * Returns: {Promise}
 
 Write `buffer` to the file.
@@ -584,10 +584,10 @@ changes:
 -->
 
 * `string` {string}
-* `position` {integer} The offset from the beginning of the file where the
+* `position` {integer|null} The offset from the beginning of the file where the
   data from `string` should be written. If `position` is not a `number` the
   data will be written at the current position. See the POSIX pwrite(2)
-  documentation for more detail.
+  documentation for more detail. **Default:** `null`
 * `encoding` {string} The expected string encoding. **Default:** `'utf8'`
 * Returns: {Promise}
 
@@ -650,9 +650,9 @@ added: v12.9.0
 -->
 
 * `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
-* `position` {integer} The offset from the beginning of the file where the
+* `position` {integer|null} The offset from the beginning of the file where the
   data from `buffers` should be written. If `position` is not a `number`,
-  the data will be written at the current position.
+  the data will be written at the current position. **Default:** `null`
 * Returns: {Promise}
 
 Write an array of {ArrayBufferView}s to the file.
@@ -3009,7 +3009,7 @@ changes:
   written to.
 * `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
+* `position` {integer|bigint|null} Specifies where to begin reading from in the
   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.
@@ -3048,7 +3048,7 @@ changes:
   * `buffer` {Buffer|TypedArray|DataView} **Default:** `Buffer.alloc(16384)`
   * `offset` {integer} **Default:** `0`
   * `length` {integer} **Default:** `buffer.byteLength - offset`
-  * `position` {integer|bigint} **Default:** `null`
+  * `position` {integer|bigint|null} **Default:** `null`
 * `callback` {Function}
   * `err` {Error}
   * `bytesRead` {integer}
@@ -3290,7 +3290,7 @@ added:
 
 * `fd` {integer}
 * `buffers` {ArrayBufferView\[]}
-* `position` {integer}
+* `position` {integer|null} **Default:** `null`
 * `callback` {Function}
   * `err` {Error}
   * `bytesRead` {integer}
@@ -3679,7 +3679,7 @@ changes:
 
 * `target` {string|Buffer|URL}
 * `path` {string|Buffer|URL}
-* `type` {string}
+* `type` {string|null} **Default:** `null`
 * `callback` {Function}
   * `err` {Error}
 
@@ -3690,8 +3690,8 @@ See the POSIX symlink(2) documentation for more details.
 
 The `type` argument is only available on Windows and ignored on other platforms.
 It can be set to `'dir'`, `'file'`, or `'junction'`. If the `type` argument is
-not set, Node.js will autodetect `target` type and use `'file'` or `'dir'`. If
-the `target` does not exist, `'file'` will be used. Windows junction points
+not a string, Node.js will autodetect `target` type and use `'file'` or `'dir'`.
+If the `target` does not exist, `'file'` will be used. Windows junction points
 require the destination path to be absolute. When using `'junction'`, the
 `target` argument will automatically be normalized to absolute path.
 
@@ -4096,9 +4096,9 @@ changes:
 
 * `fd` {integer}
 * `buffer` {Buffer|TypedArray|DataView}
-* `offset` {integer}
-* `length` {integer}
-* `position` {integer}
+* `offset` {integer} **Default:** `0`
+* `length` {integer} **Default:** `buffer.byteLength - offset`
+* `position` {integer|null} **Default:** `null`
 * `callback` {Function}
   * `err` {Error}
   * `bytesWritten` {integer}
@@ -4159,7 +4159,7 @@ changes:
 
 * `fd` {integer}
 * `string` {string|Object}
-* `position` {integer}
+* `position` {integer|null} **Default:** `null`
 * `encoding` {string} **Default:** `'utf8'`
 * `callback` {Function}
   * `err` {Error}
@@ -4348,7 +4348,7 @@ added: v12.9.0
 
 * `fd` {integer}
 * `buffers` {ArrayBufferView\[]}
-* `position` {integer}
+* `position` {integer|null} **Default:** `null`
 * `callback` {Function}
   * `err` {Error}
   * `bytesWritten` {integer}
@@ -5061,7 +5061,7 @@ object with an `encoding` property specifying the character encoding to use for
 the link path returned. If the `encoding` is set to `'buffer'`,
 the link path returned will be passed as a {Buffer} object.
 
-### `fs.readSync(fd, buffer, offset, length, position)`
+### `fs.readSync(fd, buffer, offset, length[, position])`
 
 <!-- YAML
 added: v0.1.21
@@ -5079,7 +5079,7 @@ changes:
 * `buffer` {Buffer|TypedArray|DataView}
 * `offset` {integer}
 * `length` {integer}
-* `position` {integer|bigint}
+* `position` {integer|bigint|null} **Default:** `null`
 * Returns: {number}
 
 Returns the number of `bytesRead`.
@@ -5107,7 +5107,7 @@ changes:
 * `options` {Object}
   * `offset` {integer} **Default:** `0`
   * `length` {integer} **Default:** `buffer.byteLength - offset`
-  * `position` {integer|bigint} **Default:** `null`
+  * `position` {integer|bigint|null} **Default:** `null`
 * Returns: {number}
 
 Returns the number of `bytesRead`.
@@ -5128,7 +5128,7 @@ added:
 
 * `fd` {integer}
 * `buffers` {ArrayBufferView\[]}
-* `position` {integer}
+* `position` {integer|null} **Default:** `null`
 * Returns: {number} The number of bytes read.
 
 For detailed information, see the documentation of the asynchronous version of
@@ -5350,7 +5350,7 @@ changes:
 
 * `target` {string|Buffer|URL}
 * `path` {string|Buffer|URL}
-* `type` {string}
+* `type` {string|null} **Default:** `null`
 
 Returns `undefined`.
 
@@ -5482,9 +5482,9 @@ changes:
 
 * `fd` {integer}
 * `buffer` {Buffer|TypedArray|DataView}
-* `offset` {integer}
-* `length` {integer}
-* `position` {integer}
+* `offset` {integer} **Default:** `0`
+* `length` {integer} **Default:** `buffer.byteLength - offset`
+* `position` {integer|null} **Default:** `null`
 * Returns: {number} The number of bytes written.
 
 For detailed information, see the documentation of the asynchronous version of
@@ -5506,8 +5506,8 @@ changes:
 
 * `fd` {integer}
 * `string` {string}
-* `position` {integer}
-* `encoding` {string}
+* `position` {integer|null} **Default:** `null`
+* `encoding` {string} **Default:** `'utf8'`
 * Returns: {number} The number of bytes written.
 
 For detailed information, see the documentation of the asynchronous version of
@@ -5521,7 +5521,7 @@ added: v12.9.0
 
 * `fd` {integer}
 * `buffers` {ArrayBufferView\[]}
-* `position` {integer}
+* `position` {integer|null} **Default:** `null`
 * Returns: {number} The number of bytes written.
 
 For detailed information, see the documentation of the asynchronous version of
diff --git a/lib/fs.js b/lib/fs.js
index ae9405dfa13df2..2747a592b6416a 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -593,7 +593,7 @@ function openSync(path, flags, mode) {
  * @param {Buffer | TypedArray | DataView} buffer
  * @param {number} offset
  * @param {number} length
- * @param {number | bigint} position
+ * @param {number | bigint | null} position
  * @param {(
  *   err?: Error,
  *   bytesRead?: number,
@@ -678,7 +678,7 @@ ObjectDefineProperty(read, internalUtil.customPromisifyArgs,
  * @param {{
  *   offset?: number;
  *   length?: number;
- *   position?: number | bigint;
+ *   position?: number | bigint | null;
  *   }} [offset]
  * @returns {number}
  */
@@ -734,7 +734,7 @@ function readSync(fd, buffer, offset, length, position) {
  * and writes to an array of `ArrayBufferView`s.
  * @param {number} fd
  * @param {ArrayBufferView[]} buffers
- * @param {number} [position]
+ * @param {number | null} [position]
  * @param {(
  *   err?: Error,
  *   bytesRead?: number,
@@ -769,7 +769,7 @@ ObjectDefineProperty(readv, internalUtil.customPromisifyArgs,
  * of `ArrayBufferView`s.
  * @param {number} fd
  * @param {ArrayBufferView[]} buffers
- * @param {number} [position]
+ * @param {number | null} [position]
  * @returns {number}
  */
 function readvSync(fd, buffers, position) {
@@ -792,7 +792,7 @@ function readvSync(fd, buffers, position) {
  * @param {Buffer | TypedArray | DataView | string | object} buffer
  * @param {number} [offset]
  * @param {number} [length]
- * @param {number} [position]
+ * @param {number | null} [position]
  * @param {(
  *   err?: Error,
  *   bytesWritten?: number;
@@ -857,7 +857,7 @@ ObjectDefineProperty(write, internalUtil.customPromisifyArgs,
  * @param {Buffer | TypedArray | DataView | string} buffer
  * @param {number} [offset]
  * @param {number} [length]
- * @param {number} [position]
+ * @param {number | null} [position]
  * @returns {number}
  */
 function writeSync(fd, buffer, offset, length, position) {
@@ -895,7 +895,7 @@ function writeSync(fd, buffer, offset, length, position) {
  * specified `fd` (file descriptor).
  * @param {number} fd
  * @param {ArrayBufferView[]} buffers
- * @param {number} [position]
+ * @param {number | null} [position]
  * @param {(
  *   err?: Error,
  *   bytesWritten?: number,
@@ -936,7 +936,7 @@ ObjectDefineProperty(writev, internalUtil.customPromisifyArgs, {
  * to the specified `fd` (file descriptor).
  * @param {number} fd
  * @param {ArrayBufferView[]} buffers
- * @param {number} [position]
+ * @param {number | null} [position]
  * @returns {number}
  */
 function writevSync(fd, buffers, position) {
@@ -1594,7 +1594,7 @@ function readlinkSync(path, options) {
  * Creates the link called `path` pointing to `target`.
  * @param {string | Buffer | URL} target
  * @param {string | Buffer | URL} path
- * @param {string} [type_]
+ * @param {string | null} [type_]
  * @param {(err?: Error) => any} callback_
  * @returns {void}
  */
@@ -1647,7 +1647,7 @@ function symlink(target, path, type_, callback_) {
  * pointing to `target`.
  * @param {string | Buffer | URL} target
  * @param {string | Buffer | URL} path
- * @param {string} [type]
+ * @param {string | null} [type]
  * @returns {void}
  */
 function symlinkSync(target, path, type) {