Skip to content

Commit 2b9bff3

Browse files
committed
doc: add MDN links for explicit resource management in fs
Add cross-references to MDN documentation for `using` and `await using` statements in the fs module documentation. Remove TODO comment waiting for MDN documentation availability. Fixes: #59556
1 parent 7535aa1 commit 2b9bff3

File tree

1 file changed

+24
-4
lines changed

1 file changed

+24
-4
lines changed

doc/api/fs.md

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -874,6 +874,10 @@ changes:
874874
Calls `filehandle.close()` and returns a promise that fulfills when the
875875
filehandle is closed.
876876
877+
This method enables the filehandle to be used with [`await using`][], which
878+
will automatically close the file when the scope exits. For more information,
879+
see the [MDN documentation on `using` statements][`using`].
880+
877881
### `fsPromises.access(path[, mode])`
878882
879883
<!-- YAML
@@ -1342,10 +1346,11 @@ directory cannot be deleted, disposal will throw an error. The object has an
13421346
async `remove()` method which will perform the same task.
13431347
13441348
Both this function and the disposal function on the resulting object are
1345-
async, so it should be used with `await` + `await using` as in
1349+
async, so it should be used with `await` + [`await using`] as in
13461350
`await using dir = await fsPromises.mkdtempDisposable('prefix')`.
13471351
1348-
<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
1352+
See the [MDN documentation on `using` statements][`using`] for more information about
1353+
explicit resource management.
13491354
13501355
For detailed information, see the documentation of [`fsPromises.mkdtemp()`][].
13511356
@@ -5971,12 +5976,13 @@ removed if it still exists. If the directory cannot be deleted, disposal will
59715976
throw an error. The object has a `remove()` method which will perform the same
59725977
task.
59735978
5974-
<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
5979+
See the [MDN documentation on `using` statements][`using`] for more information about
5980+
explicit resource management.
59755981
59765982
For detailed information, see the documentation of [`fs.mkdtemp()`][].
59775983
59785984
There is no callback-based version of this API because it is designed for use
5979-
with the `using` syntax.
5985+
with the [`using`][] syntax.
59805986
59815987
The optional `options` argument can be a string specifying an encoding, or an
59825988
object with an `encoding` property specifying the character encoding to use.
@@ -6838,6 +6844,10 @@ changes:
68386844
Calls `dir.close()` if the directory handle is open, and returns a promise that
68396845
fulfills when disposal is complete.
68406846
6847+
This method enables the directory to be used with [`await using`][], which
6848+
will automatically close the directory when the scope exits. For more
6849+
information, see the [MDN documentation on `using` statements][`using`].
6850+
68416851
#### `dir[Symbol.dispose]()`
68426852
68436853
<!-- YAML
@@ -6853,6 +6863,10 @@ changes:
68536863
Calls `dir.closeSync()` if the directory handle is open, and returns
68546864
`undefined`.
68556865
6866+
This method enables the directory to be used with [`using`][], which
6867+
will automatically close the directory when the scope exits. For more
6868+
information, see the [MDN documentation on `using` statements][`using`].
6869+
68566870
### Class: `fs.Dirent`
68576871
68586872
<!-- YAML
@@ -7893,6 +7907,10 @@ the `data` argument must be a {Buffer}.
78937907
78947908
Calls `utf8Stream.destroy()`.
78957909
7910+
This method enables the stream to be used with [`using`][], which
7911+
will automatically destroy the stream when the scope exits. For more
7912+
information, see the [MDN documentation on `using` statements][`using`].
7913+
78967914
### Class: `fs.WriteStream`
78977915
78987916
<!-- YAML
@@ -8708,6 +8726,7 @@ the file contents.
87088726
[`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
87098727
[`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw
87108728
[`UV_THREADPOOL_SIZE`]: cli.md#uv_threadpool_sizesize
8729+
[`await using`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/await_using
87118730
[`event ports`]: https://illumos.org/man/port_create
87128731
[`filehandle.createReadStream()`]: #filehandlecreatereadstreamoptions
87138732
[`filehandle.createWriteStream()`]: #filehandlecreatewritestreamoptions
@@ -8760,6 +8779,7 @@ the file contents.
87608779
[`fsPromises.utimes()`]: #fspromisesutimespath-atime-mtime
87618780
[`inotify(7)`]: https://man7.org/linux/man-pages/man7/inotify.7.html
87628781
[`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
8782+
[`using`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
87638783
[`util.promisify()`]: util.md#utilpromisifyoriginal
87648784
[bigints]: https://tc39.github.io/proposal-bigint
87658785
[caveats]: #caveats

0 commit comments

Comments
 (0)