Skip to content
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.

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

doc: fix some recent nits in fs.md #29906

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
86 changes: 44 additions & 42 deletions doc/api/fs.md
Expand Up @@ -291,7 +291,8 @@ added: v12.12.0

A class representing a directory stream.

Created by [`fs.opendir()`][], [`fs.opendirSync()`][], or [`fsPromises.opendir()`][].
Created by [`fs.opendir()`][], [`fs.opendirSync()`][], or
[`fsPromises.opendir()`][].

```js
const fs = require('fs');
Expand All @@ -305,16 +306,6 @@ async function print(path) {
print('./').catch(console.error);
```

### dir.path
<!-- YAML
added: v12.12.0
-->

* {string}

The read-only path of this directory as was provided to [`fs.opendir()`][],
[`fs.opendirSync()`][], or [`fsPromises.opendir()`][].

### dir.close()
<!-- YAML
added: v12.12.0
Expand Down Expand Up @@ -349,6 +340,16 @@ added: v12.12.0
Synchronously close the directory's underlying resource handle.
Subsequent reads will result in errors.

### dir.path
<!-- YAML
added: v12.12.0
-->

* {string}

The read-only path of this directory as was provided to [`fs.opendir()`][],
[`fs.opendirSync()`][], or [`fsPromises.opendir()`][].

### dir.read()
<!-- YAML
added: v12.12.0
Expand Down Expand Up @@ -429,7 +430,8 @@ included in the iteration results.
added: v10.10.0
-->

A representation of a directory entry, as returned by reading from an [`fs.Dir`][].
A representation of a directory entry, as returned by reading from an
[`fs.Dir`][].

Additionally, when [`fs.readdir()`][] or [`fs.readdirSync()`][] is called with
the `withFileTypes` option set to `true`, the resulting array is filled with
Expand Down Expand Up @@ -2620,33 +2622,6 @@ a colon, Node.js will open a file system stream, as described by
Functions based on `fs.open()` exhibit this behavior as well:
`fs.writeFile()`, `fs.readFile()`, etc.

## fs.openSync(path\[, flags, mode\])
<!-- YAML
added: v0.1.21
changes:
- version: v11.1.0
pr-url: https://github.com/nodejs/node/pull/23767
description: The `flags` argument is now optional and defaults to `'r'`.
- version: v9.9.0
pr-url: https://github.com/nodejs/node/pull/18801
description: The `as` and `as+` modes are supported now.
- version: v7.6.0
pr-url: https://github.com/nodejs/node/pull/10739
description: The `path` parameter can be a WHATWG `URL` object using `file:`
protocol. Support is currently still *experimental*.
-->

* `path` {string|Buffer|URL}
* `flags` {string|number} **Default:** `'r'`.
See [support of file system `flags`][].
* `mode` {integer} **Default:** `0o666`
* Returns: {number}

Returns an integer representing the file descriptor.

For detailed information, see the documentation of the asynchronous version of
this API: [`fs.open()`][].

## fs.opendir(path\[, options\], callback)
<!-- YAML
added: v12.12.0
Expand Down Expand Up @@ -2685,6 +2660,33 @@ and cleaning up the directory.
The `encoding` option sets the encoding for the `path` while opening the
directory and subsequent read operations.

## fs.openSync(path\[, flags, mode\])
<!-- YAML
added: v0.1.21
changes:
- version: v11.1.0
pr-url: https://github.com/nodejs/node/pull/23767
description: The `flags` argument is now optional and defaults to `'r'`.
- version: v9.9.0
pr-url: https://github.com/nodejs/node/pull/18801
description: The `as` and `as+` modes are supported now.
- version: v7.6.0
pr-url: https://github.com/nodejs/node/pull/10739
description: The `path` parameter can be a WHATWG `URL` object using `file:`
protocol. Support is currently still *experimental*.
-->

* `path` {string|Buffer|URL}
* `flags` {string|number} **Default:** `'r'`.
See [support of file system `flags`][].
* `mode` {integer} **Default:** `0o666`
* Returns: {number}

Returns an integer representing the file descriptor.

For detailed information, see the documentation of the asynchronous version of
this API: [`fs.open()`][].

## fs.read(fd, buffer, offset, length, position, callback)
<!-- YAML
added: v0.0.2
Expand Down Expand Up @@ -4824,7 +4826,7 @@ by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
a colon, Node.js will open a file system stream, as described by
[this MSDN page][MSDN-Using-Streams].

## fsPromises.opendir(path\[, options\])
### fsPromises.opendir(path\[, options\])
<!-- YAML
added: v12.12.0
-->
Expand Down Expand Up @@ -5459,6 +5461,7 @@ the file contents.
[`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding
[`Buffer`]: buffer.html#buffer_buffer
[`FSEvents`]: https://developer.apple.com/documentation/coreservices/file_system_events
[`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
[`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw
[`ReadStream`]: #fs_class_fs_readstream
[`URL`]: url.html#url_the_whatwg_url_api
Expand Down Expand Up @@ -5505,7 +5508,6 @@ the file contents.
[`net.Socket`]: net.html#net_class_net_socket
[`stat()`]: fs.html#fs_fs_stat_path_options_callback
[`util.promisify()`]: util.html#util_util_promisify_original
[bigints]: https://tc39.github.io/proposal-bigint
[Caveats]: #fs_caveats
[Common System Errors]: errors.html#errors_common_system_errors
[FS Constants]: #fs_fs_constants_1
Expand All @@ -5515,7 +5517,7 @@ the file contents.
[MSDN-Rel-Path]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths
[MSDN-Using-Streams]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams
[Naming Files, Paths, and Namespaces]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file
[bigints]: https://tc39.github.io/proposal-bigint
[chcp]: https://ss64.com/nt/chcp.html
[inode]: https://en.wikipedia.org/wiki/Inode
[support of file system `flags`]: #fs_file_system_flags
[`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER