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.

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

doc: unify and compact some fragments in fs.md #20050

Closed
wants to merge 1 commit into from
Closed

doc: unify and compact some fragments in fs.md #20050

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
73 changes: 22 additions & 51 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1298,35 +1298,20 @@ changes:

* `path` {string|Buffer|URL}
* `options` {string|Object}
* `flags` {string}
* `encoding` {string}
* `fd` {integer}
* `mode` {integer}
* `autoClose` {boolean}
* `flags` {string} **Default:** `'r'`
* `encoding` {string} **Default:** `null`
* `fd` {integer} **Default:** `null`
* `mode` {integer} **Default:** `0o666`
* `autoClose` {boolean} **Default:** `true`
* `start` {integer}
* `end` {integer}
* `highWaterMark` {integer}
* Returns: {stream.Readable}

Returns a new [`ReadStream`][] object. (See [Readable Streams][]).
* `end` {integer} **Default:** `Infinity`
* `highWaterMark` {integer} **Default:** `64 * 1024`
* Returns: {fs.ReadStream} See [Readable Streams][].

Be aware that, unlike the default value set for `highWaterMark` on a
readable stream (16 kb), the stream returned by this method has a
default value of 64 kb for the same parameter.

`options` is an object or string with the following defaults:

```js
const defaults = {
flags: 'r',
encoding: null,
fd: null,
mode: 0o666,
autoClose: true,
highWaterMark: 64 * 1024
};
```

`options` can include `start` and `end` values to read a range of bytes from
the file instead of the entire file. Both `start` and `end` are inclusive and
start counting at 0. If `fd` is specified and `start` is omitted or `undefined`,
Expand Down Expand Up @@ -1376,27 +1361,13 @@ changes:

* `path` {string|Buffer|URL}
* `options` {string|Object}
* `flags` {string}
* `encoding` {string}
* `fd` {integer}
* `mode` {integer}
* `autoClose` {boolean}
* `flags` {string} **Default:** `'w'`
* `encoding` {string} **Default:** `'utf8'`
* `fd` {integer} **Default:** `null`
* `mode` {integer} **Default:** `0o666`
* `autoClose` {boolean} **Default:** `true`
* `start` {integer}
* Returns: {stream.Writable}

Returns a new [`WriteStream`][] object. (See [Writable Stream][]).

`options` is an object or string with the following defaults:

```js
const defaults = {
flags: 'w',
encoding: 'utf8',
fd: null,
mode: 0o666,
autoClose: true
};
```
* Returns: {fs.WriteStream} See [Writable Stream][].

`options` may also include a `start` option to allow writing data at
some position past the beginning of the file. Modifying a file rather
Expand All @@ -1410,7 +1381,7 @@ then the file descriptor won't be closed, even if there's an error.
It is the application's responsibility to close it and make sure there's no
file descriptor leak.

Like [`ReadStream`][], if `fd` is specified, `WriteStream` will ignore the
Like [`ReadStream`][], if `fd` is specified, [`WriteStream`][] will ignore the
`path` argument and will use the specified file descriptor. This means that no
`'open'` event will be emitted. Note that `fd` should be blocking; non-blocking
`fd`s should be passed to [`net.Socket`][].
Expand Down Expand Up @@ -1675,7 +1646,7 @@ added: v0.1.95
* `fd` {integer}
* Returns: {fs.Stats}

Synchronous fstat(2). Returns an instance of [`fs.Stats`][].
Synchronous fstat(2).

## fs.fsync(fd, callback)
<!-- YAML
Expand Down Expand Up @@ -1978,7 +1949,7 @@ changes:
* `path` {string|Buffer|URL}
* Returns: {fs.Stats}

Synchronous lstat(2). Returns an instance of [`fs.Stats`][].
Synchronous lstat(2).

## fs.mkdir(path[, mode], callback)
<!-- YAML
Expand Down Expand Up @@ -2339,10 +2310,9 @@ changes:
* `path` {string|Buffer|URL}
* `options` {string|Object}
* `encoding` {string} **Default:** `'utf8'`
* Returns: {string[]} An array of filenames
* Returns: {string[]} An array of filenames excluding `'.'` and `'..'`.

Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
`'..'`.
Synchronous readdir(3).

The optional `options` argument can be a string specifying an encoding, or an
object with an `encoding` property specifying the character encoding to use for
Expand Down Expand Up @@ -2841,7 +2811,7 @@ changes:
* `path` {string|Buffer|URL}
* Returns: {fs.Stats}

Synchronous stat(2). Returns an instance of [`fs.Stats`][].
Synchronous stat(2).

## fs.symlink(target, path[, type], callback)
<!-- YAML
Expand Down Expand Up @@ -3094,9 +3064,10 @@ changes:
* `listener` {Function|undefined} **Default:** `undefined`
* `eventType` {string}
* `filename` {string|Buffer}
* Returns: {fs.FSWatcher}

Watch for changes on `filename`, where `filename` is either a file or a
directory. The returned object is a [`fs.FSWatcher`][].
directory.

The second argument is optional. If `options` is provided as a string, it
specifies the `encoding`. Otherwise `options` should be passed as an object.
Expand Down
3 changes: 3 additions & 0 deletions tools/doc/type-parser.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,10 @@ const customTypesMap = {
'EventEmitter': 'events.html#events_class_eventemitter',

'FileHandle': 'fs.html#fs_class_filehandle',
'fs.FSWatcher': 'fs.html#fs_class_fs_fswatcher',
'fs.ReadStream': 'fs.html#fs_class_fs_readstream',
'fs.Stats': 'fs.html#fs_class_fs_stats',
'fs.WriteStream': 'fs.html#fs_class_fs_writestream',

'http.Agent': 'http.html#http_class_http_agent',
'http.ClientRequest': 'http.html#http_class_http_clientrequest',
Expand Down