Skip to content

Commit 924670f

Browse files
LiviaMedeirosRafaelGSS
LiviaMedeiros
authored and
RafaelGSS
committed
doc: clarify some default values in fs.md
PR-URL: #42892 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]>
1 parent 72b90fd commit 924670f

File tree

2 files changed

+43
-43
lines changed

2 files changed

+43
-43
lines changed

‎doc/api/fs.md

+33-33
Original file line numberDiff line numberDiff line change
@@ -374,7 +374,7 @@ added: v10.0.0
374374
file data read.
375375
* `offset` {integer} The location in the buffer at which to start filling.
376376
* `length` {integer} The number of bytes to read.
377-
* `position` {integer} The location where to begin reading data from the
377+
* `position` {integer|null} The location where to begin reading data from the
378378
file. If `null`, data will be read from the current file position, and
379379
the position will be updated. If `position` is an integer, the current
380380
file position will remain unchanged.
@@ -403,7 +403,7 @@ added:
403403
**Default:** `0`
404404
* `length` {integer} The number of bytes to read. **Default:**
405405
`buffer.byteLength - offset`
406-
* `position` {integer} The location where to begin reading data from the
406+
* `position` {integer|null} The location where to begin reading data from the
407407
file. If `null`, data will be read from the current file position, and
408408
the position will be updated. If `position` is an integer, the current
409409
file position will remain unchanged. **Default:**: `null`
@@ -497,9 +497,9 @@ added:
497497
-->
498498
499499
* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
500-
* `position` {integer} The offset from the beginning of the file where the data
501-
should be read from. If `position` is not a `number`, the data will be read
502-
from the current position.
500+
* `position` {integer|null} The offset from the beginning of the file where
501+
the data should be read from. If `position` is not a `number`, the data will
502+
be read from the current position. **Default:** `null`
503503
* Returns: {Promise} Fulfills upon success an object containing two properties:
504504
* `bytesRead` {integer} the number of bytes read
505505
* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} property containing
@@ -597,10 +597,10 @@ changes:
597597
to write begins. **Default:** `0`
598598
* `length` {integer} The number of bytes from `buffer` to write. **Default:**
599599
`buffer.byteLength - offset`
600-
* `position` {integer} The offset from the beginning of the file where the
600+
* `position` {integer|null} The offset from the beginning of the file where the
601601
data from `buffer` should be written. If `position` is not a `number`,
602602
the data will be written at the current position. See the POSIX pwrite(2)
603-
documentation for more detail.
603+
documentation for more detail. **Default:** `null`
604604
* Returns: {Promise}
605605
606606
Write `buffer` to the file.
@@ -631,10 +631,10 @@ changes:
631631
-->
632632
633633
* `string` {string}
634-
* `position` {integer} The offset from the beginning of the file where the
634+
* `position` {integer|null} The offset from the beginning of the file where the
635635
data from `string` should be written. If `position` is not a `number` the
636636
data will be written at the current position. See the POSIX pwrite(2)
637-
documentation for more detail.
637+
documentation for more detail. **Default:** `null`
638638
* `encoding` {string} The expected string encoding. **Default:** `'utf8'`
639639
* Returns: {Promise}
640640
@@ -699,9 +699,9 @@ added: v12.9.0
699699
-->
700700
701701
* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
702-
* `position` {integer} The offset from the beginning of the file where the
702+
* `position` {integer|null} The offset from the beginning of the file where the
703703
data from `buffers` should be written. If `position` is not a `number`,
704-
the data will be written at the current position.
704+
the data will be written at the current position. **Default:** `null`
705705
* Returns: {Promise}
706706
707707
Write an array of {ArrayBufferView}s to the file.
@@ -3194,7 +3194,7 @@ changes:
31943194
written to.
31953195
* `offset` {integer} The position in `buffer` to write the data to.
31963196
* `length` {integer} The number of bytes to read.
3197-
* `position` {integer|bigint} Specifies where to begin reading from in the
3197+
* `position` {integer|bigint|null} Specifies where to begin reading from in the
31983198
file. If `position` is `null` or `-1 `, data will be read from the current
31993199
file position, and the file position will be updated. If `position` is an
32003200
integer, the file position will be unchanged.
@@ -3233,7 +3233,7 @@ changes:
32333233
* `buffer` {Buffer|TypedArray|DataView} **Default:** `Buffer.alloc(16384)`
32343234
* `offset` {integer} **Default:** `0`
32353235
* `length` {integer} **Default:** `buffer.byteLength - offset`
3236-
* `position` {integer|bigint} **Default:** `null`
3236+
* `position` {integer|bigint|null} **Default:** `null`
32373237
* `callback` {Function}
32383238
* `err` {Error}
32393239
* `bytesRead` {integer}
@@ -3498,7 +3498,7 @@ changes:
34983498

34993499
* `fd` {integer}
35003500
* `buffers` {ArrayBufferView\[]}
3501-
* `position` {integer}
3501+
* `position` {integer|null} **Default:** `null`
35023502
* `callback` {Function}
35033503
* `err` {Error}
35043504
* `bytesRead` {integer}
@@ -3920,7 +3920,7 @@ changes:
39203920

39213921
* `target` {string|Buffer|URL}
39223922
* `path` {string|Buffer|URL}
3923-
* `type` {string}
3923+
* `type` {string|null} **Default:** `null`
39243924
* `callback` {Function}
39253925
* `err` {Error}
39263926

@@ -3931,8 +3931,8 @@ See the POSIX symlink(2) documentation for more details.
39313931

39323932
The `type` argument is only available on Windows and ignored on other platforms.
39333933
It can be set to `'dir'`, `'file'`, or `'junction'`. If the `type` argument is
3934-
not set, Node.js will autodetect `target` type and use `'file'` or `'dir'`. If
3935-
the `target` does not exist, `'file'` will be used. Windows junction points
3934+
not a string, Node.js will autodetect `target` type and use `'file'` or `'dir'`.
3935+
If the `target` does not exist, `'file'` will be used. Windows junction points
39363936
require the destination path to be absolute. When using `'junction'`, the
39373937
`target` argument will automatically be normalized to absolute path.
39383938

@@ -4359,9 +4359,9 @@ changes:
43594359
43604360
* `fd` {integer}
43614361
* `buffer` {Buffer|TypedArray|DataView}
4362-
* `offset` {integer}
4363-
* `length` {integer}
4364-
* `position` {integer}
4362+
* `offset` {integer} **Default:** `0`
4363+
* `length` {integer} **Default:** `buffer.byteLength - offset`
4364+
* `position` {integer|null} **Default:** `null`
43654365
* `callback` {Function}
43664366
* `err` {Error}
43674367
* `bytesWritten` {integer}
@@ -4422,7 +4422,7 @@ changes:
44224422
44234423
* `fd` {integer}
44244424
* `string` {string|Object}
4425-
* `position` {integer}
4425+
* `position` {integer|null} **Default:** `null`
44264426
* `encoding` {string} **Default:** `'utf8'`
44274427
* `callback` {Function}
44284428
* `err` {Error}
@@ -4623,7 +4623,7 @@ changes:
46234623
46244624
* `fd` {integer}
46254625
* `buffers` {ArrayBufferView\[]}
4626-
* `position` {integer}
4626+
* `position` {integer|null} **Default:** `null`
46274627
* `callback` {Function}
46284628
* `err` {Error}
46294629
* `bytesWritten` {integer}
@@ -5338,7 +5338,7 @@ object with an `encoding` property specifying the character encoding to use for
53385338
the link path returned. If the `encoding` is set to `'buffer'`,
53395339
the link path returned will be passed as a {Buffer} object.
53405340
5341-
### `fs.readSync(fd, buffer, offset, length, position)`
5341+
### `fs.readSync(fd, buffer, offset, length[, position])`
53425342
53435343
<!-- YAML
53445344
added: v0.1.21
@@ -5356,7 +5356,7 @@ changes:
53565356
* `buffer` {Buffer|TypedArray|DataView}
53575357
* `offset` {integer}
53585358
* `length` {integer}
5359-
* `position` {integer|bigint}
5359+
* `position` {integer|bigint|null} **Default:** `null`
53605360
* Returns: {number}
53615361
53625362
Returns the number of `bytesRead`.
@@ -5384,7 +5384,7 @@ changes:
53845384
* `options` {Object}
53855385
* `offset` {integer} **Default:** `0`
53865386
* `length` {integer} **Default:** `buffer.byteLength - offset`
5387-
* `position` {integer|bigint} **Default:** `null`
5387+
* `position` {integer|bigint|null} **Default:** `null`
53885388
* Returns: {number}
53895389
53905390
Returns the number of `bytesRead`.
@@ -5405,7 +5405,7 @@ added:
54055405
54065406
* `fd` {integer}
54075407
* `buffers` {ArrayBufferView\[]}
5408-
* `position` {integer}
5408+
* `position` {integer|null} **Default:** `null`
54095409
* Returns: {number} The number of bytes read.
54105410
54115411
For detailed information, see the documentation of the asynchronous version of
@@ -5629,7 +5629,7 @@ changes:
56295629
56305630
* `target` {string|Buffer|URL}
56315631
* `path` {string|Buffer|URL}
5632-
* `type` {string}
5632+
* `type` {string|null} **Default:** `null`
56335633
56345634
Returns `undefined`.
56355635
@@ -5761,9 +5761,9 @@ changes:
57615761
57625762
* `fd` {integer}
57635763
* `buffer` {Buffer|TypedArray|DataView}
5764-
* `offset` {integer}
5765-
* `length` {integer}
5766-
* `position` {integer}
5764+
* `offset` {integer} **Default:** `0`
5765+
* `length` {integer} **Default:** `buffer.byteLength - offset`
5766+
* `position` {integer|null} **Default:** `null`
57675767
* Returns: {number} The number of bytes written.
57685768
57695769
For detailed information, see the documentation of the asynchronous version of
@@ -5785,8 +5785,8 @@ changes:
57855785
57865786
* `fd` {integer}
57875787
* `string` {string}
5788-
* `position` {integer}
5789-
* `encoding` {string}
5788+
* `position` {integer|null} **Default:** `null`
5789+
* `encoding` {string} **Default:** `'utf8'`
57905790
* Returns: {number} The number of bytes written.
57915791
57925792
For detailed information, see the documentation of the asynchronous version of
@@ -5800,7 +5800,7 @@ added: v12.9.0
58005800
58015801
* `fd` {integer}
58025802
* `buffers` {ArrayBufferView\[]}
5803-
* `position` {integer}
5803+
* `position` {integer|null} **Default:** `null`
58045804
* Returns: {number} The number of bytes written.
58055805
58065806
For detailed information, see the documentation of the asynchronous version of

‎lib/fs.js

+10-10
Original file line numberDiff line numberDiff line change
@@ -597,7 +597,7 @@ function openSync(path, flags, mode) {
597597
* @param {Buffer | TypedArray | DataView} buffer
598598
* @param {number} offset
599599
* @param {number} length
600-
* @param {number | bigint} position
600+
* @param {number | bigint | null} position
601601
* @param {(
602602
* err?: Error,
603603
* bytesRead?: number,
@@ -682,7 +682,7 @@ ObjectDefineProperty(read, internalUtil.customPromisifyArgs,
682682
* @param {{
683683
* offset?: number;
684684
* length?: number;
685-
* position?: number | bigint;
685+
* position?: number | bigint | null;
686686
* }} [offset]
687687
* @returns {number}
688688
*/
@@ -738,7 +738,7 @@ function readSync(fd, buffer, offset, length, position) {
738738
* and writes to an array of `ArrayBufferView`s.
739739
* @param {number} fd
740740
* @param {ArrayBufferView[]} buffers
741-
* @param {number} [position]
741+
* @param {number | null} [position]
742742
* @param {(
743743
* err?: Error,
744744
* bytesRead?: number,
@@ -773,7 +773,7 @@ ObjectDefineProperty(readv, internalUtil.customPromisifyArgs,
773773
* of `ArrayBufferView`s.
774774
* @param {number} fd
775775
* @param {ArrayBufferView[]} buffers
776-
* @param {number} [position]
776+
* @param {number | null} [position]
777777
* @returns {number}
778778
*/
779779
function readvSync(fd, buffers, position) {
@@ -796,7 +796,7 @@ function readvSync(fd, buffers, position) {
796796
* @param {Buffer | TypedArray | DataView | string | object} buffer
797797
* @param {number} [offset]
798798
* @param {number} [length]
799-
* @param {number} [position]
799+
* @param {number | null} [position]
800800
* @param {(
801801
* err?: Error,
802802
* bytesWritten?: number;
@@ -864,7 +864,7 @@ ObjectDefineProperty(write, internalUtil.customPromisifyArgs,
864864
* @param {Buffer | TypedArray | DataView | string} buffer
865865
* @param {number} [offset]
866866
* @param {number} [length]
867-
* @param {number} [position]
867+
* @param {number | null} [position]
868868
* @returns {number}
869869
*/
870870
function writeSync(fd, buffer, offset, length, position) {
@@ -902,7 +902,7 @@ function writeSync(fd, buffer, offset, length, position) {
902902
* specified `fd` (file descriptor).
903903
* @param {number} fd
904904
* @param {ArrayBufferView[]} buffers
905-
* @param {number} [position]
905+
* @param {number | null} [position]
906906
* @param {(
907907
* err?: Error,
908908
* bytesWritten?: number,
@@ -943,7 +943,7 @@ ObjectDefineProperty(writev, internalUtil.customPromisifyArgs, {
943943
* to the specified `fd` (file descriptor).
944944
* @param {number} fd
945945
* @param {ArrayBufferView[]} buffers
946-
* @param {number} [position]
946+
* @param {number | null} [position]
947947
* @returns {number}
948948
*/
949949
function writevSync(fd, buffers, position) {
@@ -1601,7 +1601,7 @@ function readlinkSync(path, options) {
16011601
* Creates the link called `path` pointing to `target`.
16021602
* @param {string | Buffer | URL} target
16031603
* @param {string | Buffer | URL} path
1604-
* @param {string} [type_]
1604+
* @param {string | null} [type_]
16051605
* @param {(err?: Error) => any} callback_
16061606
* @returns {void}
16071607
*/
@@ -1654,7 +1654,7 @@ function symlink(target, path, type_, callback_) {
16541654
* pointing to `target`.
16551655
* @param {string | Buffer | URL} target
16561656
* @param {string | Buffer | URL} path
1657-
* @param {string} [type]
1657+
* @param {string | null} [type]
16581658
* @returns {void}
16591659
*/
16601660
function symlinkSync(target, path, type) {

0 commit comments

Comments
 (0)