Skip to content

[v14.x backport] doc: refactor fs docs structure #39706

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
targos wants to merge 6 commits into from
Closed

[v14.x backport] doc: refactor fs docs structure #39706

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2ed0c3f
squash: make fs.md identical to master
targos Aug 8, 2021
136c98d
squash: restore lost changes entry in dgram.md
targos Aug 8, 2021
6a5c4c5
doc: refactor fs docs structure
jasnell Feb 1, 2021
29dafe9
squash: revert bad changes from d96326935ba939bfcd18c4cac525dd108a54032c
targos Aug 8, 2021
e912108
doc: change lang info string in fs JS snippets
aduh95 Mar 4, 2021
2f751eb
Apply suggestions from code review
targos Sep 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
squash: revert bad changes from d963269
  • Loading branch information
@targos
targos committed Sep 1, 2021
commit 29dafe9c6a7e822f5c0b3f8da946a65d5ae555bd
56 changes: 16 additions & 40 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,14 +174,6 @@ helping to prevent memory leaks. Please do not rely on this behavior because
it can be unreliable and the file may not be closed. Instead, always explicitly
close {FileHandle}s. Node.js may change this behavior in the future.

#### Event: `'close'`
<!-- YAML
added: v15.4.0
-->

The `'close'` event is emitted when the {FileHandle} has been closed and can no
longer be used.

#### `filehandle.appendFile(data[, options])`
<!-- YAML
added: v10.0.0
Expand Down Expand Up @@ -334,9 +326,7 @@ of the file.

#### `filehandle.readv(buffers[, position])`
<!-- YAML
added:
- v13.13.0
- v12.17.0
added: v14.0.0
Comment thread
targos marked this conversation as resolved.
Outdated
-->

* `buffers` {Buffer[]|TypedArray[]|DataView[]}
Expand Down Expand Up @@ -940,7 +930,7 @@ try {
<!-- YAML
added: v10.0.0
changes:
- version: v15.2.0
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/35911
description: The options argument may include an AbortSignal to abort an
ongoing readFile request.
Expand Down Expand Up @@ -1193,7 +1183,7 @@ The `atime` and `mtime` arguments follow these rules:
<!-- YAML
added: v10.0.0
changes:
- version: v15.2.0
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/35993
description: The options argument may include an AbortSignal to abort an
ongoing writeFile request.
Expand Down Expand Up @@ -1650,7 +1640,7 @@ See the POSIX chown(2) documentation for more detail.
<!-- YAML
added: v0.0.2
changes:
- version: REPLACEME
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/37174
description: A default callback is now used if one is not provided.
- version: v10.0.0
Expand Down Expand Up @@ -1729,10 +1719,6 @@ copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback);
<!-- YAML
added: v0.1.31
changes:
- version:
- v15.4.0
pr-url: https://github.com/nodejs/node/pull/35922
description: The `fd` option accepts FileHandle arguments.
- version: v14.0.0
pr-url: https://github.com/nodejs/node/pull/31408
description: Change `emitClose` default to `true`.
Expand Down Expand Up @@ -1767,7 +1753,7 @@ changes:
* `flags` {string} See [support of file system `flags`][]. **Default:**
`'r'`.
* `encoding` {string} **Default:** `null`
* `fd` {integer|FileHandle} **Default:** `null`
* `fd` {integer} **Default:** `null`
* `mode` {integer} **Default:** `0o666`
* `autoClose` {boolean} **Default:** `true`
* `emitClose` {boolean} **Default:** `true`
Expand Down Expand Up @@ -1846,10 +1832,6 @@ If `options` is a string, then it specifies the encoding.
<!-- YAML
added: v0.1.31
changes:
- version:
- v15.4.0
pr-url: https://github.com/nodejs/node/pull/35922
description: The `fd` option accepts FileHandle arguments.
- version: v14.0.0
pr-url: https://github.com/nodejs/node/pull/31408
description: Change `emitClose` default to `true`.
Expand Down Expand Up @@ -1882,7 +1864,7 @@ changes:
* `flags` {string} See [support of file system `flags`][]. **Default:**
`'w'`.
* `encoding` {string} **Default:** `'utf8'`
* `fd` {integer|FileHandle} **Default:** `null`
* `fd` {integer} **Default:** `null`
* `mode` {integer} **Default:** `0o666`
* `autoClose` {boolean} **Default:** `true`
* `emitClose` {boolean} **Default:** `true`
Expand Down Expand Up @@ -2756,7 +2738,7 @@ If `options.withFileTypes` is set to `true`, the `files` array will contain
<!-- YAML
added: v0.1.29
changes:
- version: v15.2.0
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/35911
description: The options argument may include an AbortSignal to abort an
ongoing readFile request.
Expand Down Expand Up @@ -3459,7 +3441,7 @@ The `atime` and `mtime` arguments follow these rules:
<!-- YAML
added: v0.5.10
changes:
- version: REPLACEME
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/37190
description: Added support for closing the watcher with an AbortSignal.
- version: v7.6.0
Expand Down Expand Up @@ -3534,11 +3516,11 @@ to be notified of filesystem changes.
directories.
* On SunOS systems (including Solaris and SmartOS), this uses [`event ports`][].
* On Windows systems, this feature depends on [`ReadDirectoryChangesW`][].
* On Aix systems, this feature depends on [`AHAFS`][], which must be enabled.
* On AIX systems, this feature depends on [`AHAFS`][], which must be enabled.
* On IBM i systems, this feature is not supported.

If the underlying functionality is not available for some reason, then
`fs.watch()` will not be able to function and may thrown an exception.
`fs.watch()` will not be able to function and may throw an exception.
For example, watching files or directories can be unreliable, and in some
cases impossible, on network file systems (NFS, SMB, etc) or host file systems
when using virtualization software such as Vagrant or Docker.
Expand Down Expand Up @@ -3784,7 +3766,7 @@ details.
<!-- YAML
added: v0.1.29
changes:
- version: v15.2.0
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/35993
description: The options argument may include an AbortSignal to abort an
ongoing writeFile request.
Expand Down Expand Up @@ -4331,7 +4313,7 @@ link(2) documentation for more detail. Returns `undefined`.
<!-- YAML
added: v0.1.30
changes:
- version: v15.3.0
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/33716
description: Accepts a `throwIfNoEntry` option to specify whether
an exception should be thrown if the entry does not exist.
Expand Down Expand Up @@ -4584,13 +4566,9 @@ this API: [`fs.read()`][].

### `fs.readSync(fd, buffer, [options])`
<!-- YAML
added:
- v13.13.0
- v12.17.0
added: v14.0.0
changes:
- version:
- v13.13.0
- v12.17.0
- version: v14.0.0
pr-url: https://github.com/nodejs/node/pull/32460
description: Options object can be passed in
to make offset, length and position optional.
Expand All @@ -4614,9 +4592,7 @@ this API: [`fs.read()`][].

### `fs.readvSync(fd, buffers[, position])`
<!-- YAML
added:
- v13.13.0
- v12.17.0
added: v14.0.0
Comment thread
targos marked this conversation as resolved.
Outdated
-->

* `fd` {integer}
Expand Down Expand Up @@ -4773,7 +4749,7 @@ utility). Returns `undefined`.
<!-- YAML
added: v0.1.21
changes:
- version: v15.3.0
- version: v14.17.0
pr-url: https://github.com/nodejs/node/pull/33716
description: Accepts a `throwIfNoEntry` option to specify whether
an exception should be thrown if the entry does not exist.
Expand Down