FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: make minor edits for consistency · nodejs/node@af360ac · GitHub

/ node Public

Commit af360ac

Browse files
Trott
authored and
danielleadams
committed
doc: make minor edits for consistency
* We use _noop_ and _no-op_ in different docs. Use _no-op_ everywhere. * When referring to functions, add _()_ to indicate that. * Remove backticks from non-code _destroyed_. PR-URL: #35377 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
1 parent 52657b3 commit af360ac

2 files changed

Lines changed: 117 additions & 10 deletions

File tree

‎doc/api/async_hooks.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ of asynchronous operations.
182182
* Returns: {AsyncHook} A reference to `asyncHook`.
183183

184184
Enable the callbacks for a given `AsyncHook` instance. If no callbacks are
185-
provided enabling is a noop.
185+
provided, enabling is a no-op.
186186

187187
The `AsyncHook` instance is disabled by default. If the `AsyncHook` instance
188188
should be enabled immediately after creation, the following pattern can be used.

‎doc/api/stream.md‎

Lines changed: 116 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,7 @@ added: v8.0.0
382382
changes:
383383
- version: v14.0.0
384384
pr-url: https://github.com/nodejs/node/pull/29197
385-
description: Work as noop when called on an already `destroyed` stream.
385+
description: Work as a no-op on a stream that has already been destroyed.
386386
-->
387387

388388
* `error` {Error} Optional, an error to emit with `'error'` event.
@@ -397,8 +397,8 @@ This is a destructive and immediate way to destroy a stream. Previous calls to
397397
Use `end()` instead of destroy if data should flush before close, or wait for
398398
the `'drain'` event before destroying the stream.
399399

400-
Once `destroy()` has been called any further calls will be a noop and no
401-
further errors except from `_destroy` may be emitted as `'error'`.
400+
Once `destroy()` has been called any further calls will be a no-op and no
401+
further errors except from `_destroy()` may be emitted as `'error'`.
402402

403403
Implementors should not override this method,
404404
but instead implement [`writable._destroy()`][writable-_destroy].
@@ -968,7 +968,7 @@ added: v8.0.0
968968
changes:
969969
- version: v14.0.0
970970
pr-url: https://github.com/nodejs/node/pull/29197
971-
description: Work as noop when called on an already `destroyed` stream.
971+
description: Work as a no-op on a stream that has already been destroyed.
972972
-->
973973

974974
* `error` {Error} Error which will be passed as payload in `'error'` event
@@ -979,8 +979,8 @@ event (unless `emitClose` is set to `false`). After this call, the readable
979979
stream will release any internal resources and subsequent calls to `push()`
980980
will be ignored.
981981

982-
Once `destroy()` has been called any further calls will be a noop and no
983-
further errors except from `_destroy` may be emitted as `'error'`.
982+
Once `destroy()` has been called any further calls will be a no-op and no
983+
further errors except from `_destroy()` may be emitted as `'error'`.
984984

985985
Implementors should not override this method, but instead implement
986986
[`readable._destroy()`][readable-_destroy].
@@ -1536,7 +1536,7 @@ added: v8.0.0
15361536
changes:
15371537
- version: v14.0.0
15381538
pr-url: https://github.com/nodejs/node/pull/29197
1539-
description: Work as noop when called on an already `destroyed` stream.
1539+
description: Work as a no-op on a stream that has already been destroyed.
15401540
-->
15411541

15421542
* `error` {Error}
@@ -1549,8 +1549,8 @@ Implementors should not override this method, but instead implement
15491549
The default implementation of `_destroy()` for `Transform` also emit `'close'`
15501550
unless `emitClose` is set in false.
15511551

1552-
Once `destroy()` has been called any further calls will be a noop and no
1553-
further errors except from `_destroy` may be emitted as `'error'`.
1552+
Once `destroy()` has been called, any further calls will be a no-op and no
1553+
further errors except from `_destroy()` may be emitted as `'error'`.
15541554

15551555
### `stream.finished(stream[, options], callback)`
15561556
<!-- YAML
@@ -1953,6 +1953,56 @@ const myWritable = new Writable({
19531953
});
19541954
```
19551955

1956+
#### `writable._construct(callback)`
1957+
<!-- YAML
1958+
added: REPLACEME
1959+
-->
1960+
1961+
* `callback` {Function} Call this function (optionally with an error
1962+
argument) when the stream has finished initializing.
1963+
1964+
The `_construct()` method MUST NOT be called directly. It may be implemented
1965+
by child classes, and if so, will be called by the internal `Writable`
1966+
class methods only.
1967+
1968+
This optional function will be called in a tick after the stream constructor
1969+
has returned, delaying any `_write()`, `_final()` and `_destroy()` calls until
1970+
`callback` is called. This is useful to initialize state or asynchronously
1971+
initialize resources before the stream can be used.
1972+
1973+
```js
1974+
const { Writable } = require('stream');
1975+
const fs = require('fs');
1976+
1977+
class WriteStream extends Writable {
1978+
constructor(filename) {
1979+
super();
1980+
this.filename = filename;
1981+
this.fd = fd;
1982+
}
1983+
_construct(callback) {
1984+
fs.open(this.filename, (fd, err) => {
1985+
if (err) {
1986+
callback(err);
1987+
} else {
1988+
this.fd = fd;
1989+
callback();
1990+
}
1991+
});
1992+
}
1993+
_write(chunk, encoding, callback) {
1994+
fs.write(this.fd, chunk, callback);
1995+
}
1996+
_destroy(err, callback) {
1997+
if (this.fd) {
1998+
fs.close(this.fd, (er) => callback(er || err));
1999+
} else {
2000+
callback(err);
2001+
}
2002+
}
2003+
}
2004+
```
2005+
19562006
#### `writable._write(chunk, encoding, callback)`
19572007
<!-- YAML
19582008
changes:
@@ -2219,6 +2269,63 @@ const myReadable = new Readable({
22192269
});
22202270
```
22212271

2272+
#### `readable._construct(callback)`
2273+
<!-- YAML
2274+
added: REPLACEME
2275+
-->
2276+
2277+
* `callback` {Function} Call this function (optionally with an error
2278+
argument) when the stream has finished initializing.
2279+
2280+
The `_construct()` method MUST NOT be called directly. It may be implemented
2281+
by child classes, and if so, will be called by the internal `Readable`
2282+
class methods only.
2283+
2284+
This optional function will be scheduled in the next tick by the stream
2285+
constructor, delaying any `_read()` and `_destroy()` calls until `callback` is
2286+
called. This is useful to initialize state or asynchronously initialize
2287+
resources before the stream can be used.
2288+
2289+
```js
2290+
const { Readable } = require('stream');
2291+
const fs = require('fs');
2292+
2293+
class ReadStream extends Readable {
2294+
constructor(filename) {
2295+
super();
2296+
this.filename = filename;
2297+
this.fd = null;
2298+
}
2299+
_construct(callback) {
2300+
fs.open(this.filename, (fd, err) => {
2301+
if (err) {
2302+
callback(err);
2303+
} else {
2304+
this.fd = fd;
2305+
callback();
2306+
}
2307+
});
2308+
}
2309+
_read(n) {
2310+
const buf = Buffer.alloc(n);
2311+
fs.read(this.fd, buf, 0, n, null, (err, bytesRead) => {
2312+
if (err) {
2313+
this.destroy(err);
2314+
} else {
2315+
this.push(bytesRead > 0 ? buf.slice(0, bytesRead) : null);
2316+
}
2317+
});
2318+
}
2319+
_destroy(err, callback) {
2320+
if (this.fd) {
2321+
fs.close(this.fd, (er) => callback(er || err));
2322+
} else {
2323+
callback(err);
2324+
}
2325+
}
2326+
}
2327+
```
2328+
22222329
#### `readable._read(size)`
22232330
<!-- YAML
22242331
added: v0.9.4

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL