Skip to content

Commit

Permalink
doc: remove extraneous "for example" text
Browse files Browse the repository at this point in the history
No need to announce obvious example code as being example code. Remove
unneeded "for example" text as one small way to try to keep the docs
more concise..

PR-URL: #18890
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Matheus Marchini <matheus@sthima.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Trott authored and Benjamin Gruenbaum committed Feb 23, 2018

Verified

This commit was signed with the committer’s verified signature.
not-an-aardvark Teddy Katz
1 parent 54cb3c5 commit 9cb96ac
Showing 22 changed files with 12 additions and 127 deletions.
2 changes: 1 addition & 1 deletion doc/api/addons.md
Original file line number Diff line number Diff line change
@@ -292,7 +292,7 @@ Each of these examples using the following `binding.gyp` file:
```

In cases where there is more than one `.cc` file, simply add the additional
filename to the `sources` array. For example:
filename to the `sources` array:

```json
"sources": ["addon.cc", "myexample.cc"]
8 changes: 1 addition & 7 deletions doc/api/async_hooks.md
Original file line number Diff line number Diff line change
@@ -451,8 +451,6 @@ Note that `resolve()` does not do any observable synchronous work.
rejected at this point, if the `Promise` was resolved by assuming the state
of another `Promise`.

For example:

```js
new Promise((resolve) => resolve(true)).then((a) => {});
```
@@ -481,8 +479,6 @@ changes:
* Returns: {number} The `asyncId` of the current execution context. Useful to
track when something calls.

For example:

```js
const async_hooks = require('async_hooks');

@@ -493,7 +489,7 @@ fs.open(path, 'r', (err, fd) => {
```

The ID returned from `executionAsyncId()` is related to execution timing, not
causality (which is covered by `triggerAsyncId()`). For example:
causality (which is covered by `triggerAsyncId()`):

```js
const server = net.createServer(function onConnection(conn) {
@@ -517,8 +513,6 @@ See the section on [promise execution tracking][].
* Returns: {number} The ID of the resource responsible for calling the callback
that is currently being executed.

For example:

```js
const server = net.createServer((conn) => {
// The resource that caused (or triggered) this callback to be called
4 changes: 0 additions & 4 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
@@ -925,8 +925,6 @@ added: v8.2.0
For objects whose `valueOf()` function returns a value not strictly equal to
`object`, returns `Buffer.from(object.valueOf(), offsetOrEncoding, length)`.

For example:

```js
const buf = Buffer.from(new String('this is a test'));
// Prints: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
@@ -935,8 +933,6 @@ const buf = Buffer.from(new String('this is a test'));
For objects that support `Symbol.toPrimitive`, returns
`Buffer.from(object[Symbol.toPrimitive](), offsetOrEncoding, length)`.

For example:

```js
class Foo {
[Symbol.toPrimitive]() {
2 changes: 0 additions & 2 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
@@ -225,8 +225,6 @@ a Promise for an object with `stdout` and `stderr` properties. In case of an
error, a rejected promise is returned, with the same `error` object given in the
callback, but with an additional two properties `stdout` and `stderr`.

For example:

```js
const util = require('util');
const exec = util.promisify(require('child_process').exec);
6 changes: 0 additions & 6 deletions doc/api/dns.md
Original file line number Diff line number Diff line change
@@ -114,8 +114,6 @@ Returns an array of IP address strings, formatted according to [rfc5952][],
that are currently configured for DNS resolution. A string will include a port
section if a custom port is used.

For example:

<!-- eslint-disable semi-->
```js
[
@@ -369,8 +367,6 @@ function will contain an array of objects with the following properties:
* `order`
* `preference`

For example:

<!-- eslint-skip -->
```js
{
@@ -558,8 +554,6 @@ Sets the IP address and port of servers to be used when performing DNS
resolution. The `servers` argument is an array of [rfc5952][] formatted
addresses. If the port is the IANA default DNS port (53) it can be omitted.

For example:

```js
dns.setServers([
'4.4.4.4',
2 changes: 0 additions & 2 deletions doc/api/domain.md
Original file line number Diff line number Diff line change
@@ -239,8 +239,6 @@ perhaps we would like to have a separate domain to use for each request.

That is possible via explicit binding.

For example:

```js
// create a top-level domain for the server
const domain = require('domain');
11 changes: 2 additions & 9 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
@@ -292,8 +292,6 @@ console.error(err.message);
The `error.stack` property is a string describing the point in the code at which
the `Error` was instantiated.

For example:

```txt
Error: Things keep happening!
at /home/gbusey/file.js:525:2
@@ -368,8 +366,6 @@ detailed [here](#errors_system_errors).
A subclass of `Error` that indicates the failure of an assertion. Such errors
commonly indicate inequality of actual and expected value.

For example:

```js
assert.strictEqual(1, 2);
// AssertionError [ERR_ASSERTION]: 1 === 2
@@ -381,8 +377,6 @@ A subclass of `Error` that indicates that a provided argument was not within the
set or range of acceptable values for a function; whether that is a numeric
range, or outside the set of options for a given function parameter.

For example:

```js
require('net').connect(-1);
// throws "RangeError: "port" option should be >= 0 and < 65536: -1"
@@ -1309,9 +1303,8 @@ compiled with ICU support.
<a id="ERR_NO_LONGER_SUPPORTED"></a>
### ERR_NO_LONGER_SUPPORTED

A Node.js API was called in an unsupported manner.

For example: `Buffer.write(string, encoding, offset[, length])`
A Node.js API was called in an unsupported manner, such as
`Buffer.write(string, encoding, offset[, length])`.

<a id="ERR_OUT_OF_RANGE"></a>
### ERR_OUT_OF_RANGE
10 changes: 0 additions & 10 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
@@ -22,8 +22,6 @@ The arguments passed to the completion callback depend on the method, but the
first argument is always reserved for an exception. If the operation was
completed successfully, then the first argument will be `null` or `undefined`.

For example:

```js
const fs = require('fs');

@@ -36,8 +34,6 @@ fs.unlink('/tmp/hello', (err) => {
Exceptions that occur using synchronous operations are thrown immediately and
may be handled using `try`/`catch`, or may be allowed to bubble up.

For example:

```js
const fs = require('fs');

@@ -402,7 +398,6 @@ A `fs.Stats` object provides information about a file.
Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and
their synchronous counterparts are of this type.

For example:
```console
Stats {
dev: 2114,
@@ -703,9 +698,6 @@ so introduces a race condition, since other processes may change the file's
state between the two calls. Instead, user code should open/read/write the
file directly and handle the error raised if the file is not accessible.

For example:


**write (NOT RECOMMENDED)**

```js
@@ -1356,8 +1348,6 @@ so introduces a race condition, since other processes may change the file's
state between the two calls. Instead, user code should open/read/write the
file directly and handle the error raised if the file does not exist.

For example:

**write (NOT RECOMMENDED)**

```js
4 changes: 0 additions & 4 deletions doc/api/http2.md
Original file line number Diff line number Diff line change
@@ -1090,8 +1090,6 @@ received for this stream from the connected HTTP/2 server. The listener is
invoked with two arguments: an Object containing the received
[HTTP2 Headers Object][], and flags associated with the headers.

For example:

```js
const http2 = require('http2');
const client = http2.connect('https://localhost');
@@ -2001,8 +1999,6 @@ keys will be serialized to lower-case. Property values should be strings (if
they are not they will be coerced to strings) or an Array of strings (in order
to send more than one value per header field).

For example:

```js
const headers = {
':status': '200',
2 changes: 1 addition & 1 deletion doc/api/modules.md
Original file line number Diff line number Diff line change
@@ -729,7 +729,7 @@ exports = { hello: false }; // Not exported, only available in the module
```

When the `module.exports` property is being completely replaced by a new
object, it is common to also reassign `exports`, for example:
object, it is common to also reassign `exports`:

<!-- eslint-disable func-name-matching -->
```js
4 changes: 2 additions & 2 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
@@ -59,8 +59,8 @@ example is: [node-api](https://github.com/nodejs/node-api).

In order to use the N-API functions, include the file
[node_api.h](https://github.com/nodejs/node/blob/master/src/node_api.h)
which is located in the src directory in the node development tree.
For example:
which is located in the src directory in the node development tree:

```C
#include <node_api.h>
```
2 changes: 0 additions & 2 deletions doc/api/os.md
Original file line number Diff line number Diff line change
@@ -70,8 +70,6 @@ The properties included on each object include:
* `idle` {number} The number of milliseconds the CPU has spent in idle mode.
* `irq` {number} The number of milliseconds the CPU has spent in irq mode.

For example:

<!-- eslint-disable semi -->
```js
[
10 changes: 0 additions & 10 deletions doc/api/path.md
Original file line number Diff line number Diff line change
@@ -79,8 +79,6 @@ The `path.basename()` methods returns the last portion of a `path`, similar to
the Unix `basename` command. Trailing directory separators are ignored, see
[`path.sep`][].

For example:

```js
path.basename('/foo/bar/baz/asdf/quux.html');
// Returns: 'quux.html'
@@ -140,8 +138,6 @@ The `path.dirname()` method returns the directory name of a `path`, similar to
the Unix `dirname` command. Trailing directory separators are ignored, see
[`path.sep`][].

For example:

```js
path.dirname('/foo/bar/baz/asdf/quux');
// Returns: '/foo/bar/baz/asdf'
@@ -167,8 +163,6 @@ the `path`. If there is no `.` in the last portion of the `path`, or if the
first character of the basename of `path` (see `path.basename()`) is `.`, then
an empty string is returned.

For example:

```js
path.extname('index.html');
// Returns: '.html'
@@ -302,8 +296,6 @@ Zero-length `path` segments are ignored. If the joined path string is a
zero-length string then `'.'` will be returned, representing the current
working directory.

For example:

```js
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
// Returns: '/foo/bar/baz/asdf'
@@ -497,8 +489,6 @@ Zero-length `path` segments are ignored.
If no `path` segments are passed, `path.resolve()` will return the absolute path
of the current working directory.

For example:

```js
path.resolve('/foo/bar', './baz');
// Returns: '/foo/bar/baz'
20 changes: 0 additions & 20 deletions doc/api/process.md
Original file line number Diff line number Diff line change
@@ -58,8 +58,6 @@ The listener callback function is invoked with the exit code specified either
by the [`process.exitCode`][] property, or the `exitCode` argument passed to the
[`process.exit()`] method, as the only argument.

For example:

```js
process.on('exit', (code) => {
console.log(`About to exit with code: ${code}`);
@@ -129,8 +127,6 @@ In asynchronous code, the `'unhandledRejection'` event is emitted when the list
of unhandled rejections grows, and the `'rejectionHandled'` event is emitted
when the list of unhandled rejections shrinks.

For example:

```js
const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, p) => {
@@ -161,8 +157,6 @@ behavior.
The listener function is called with the `Error` object passed as the only
argument.

For example:

```js
process.on('uncaughtException', (err) => {
fs.writeSync(1, `Caught exception: ${err}\n`);
@@ -230,8 +224,6 @@ The listener function is called with the following arguments:
(typically an [`Error`][] object).
* `p` the `Promise` that was rejected.

For example:

```js
process.on('unhandledRejection', (reason, p) => {
console.log('Unhandled Rejection at:', p, 'reason:', reason);
@@ -355,8 +347,6 @@ The signal handler will receive the signal's name (`'SIGINT'`,
The name of each event will be the uppercase common name for the signal (e.g.
`'SIGINT'` for `SIGINT` signals).

For example:

```js
// Begin reading from stdin so the process does not exit.
process.stdin.resume();
@@ -924,8 +914,6 @@ include the Node.js executable, the name of the script, or any options following
the script name. These options are useful in order to spawn child processes with
the same execution environment as the parent.

For example:

```console
$ node --harmony script.js --version
```
@@ -954,8 +942,6 @@ added: v0.1.100
The `process.execPath` property returns the absolute pathname of the executable
that started the Node.js process.

For example:

<!-- eslint-disable semi -->
```js
'/usr/local/bin/node'
@@ -1227,8 +1213,6 @@ Even though the name of this function is `process.kill()`, it is really just a
signal sender, like the `kill` system call. The signal sent may do something
other than kill the target process.

For example:

```js
process.on('SIGHUP', () => {
console.log('Got SIGHUP signal.');
@@ -1504,8 +1488,6 @@ tarball.
- `'Boron'` for the 6.x LTS line beginning with 6.9.0.
- `'Carbon'` for the 8.x LTS line beginning with 8.9.1.

For example:

<!-- eslint-skip -->
```js
{
@@ -1709,8 +1691,6 @@ The `process.stdin` property returns a stream connected to
stream) unless fd `0` refers to a file, in which case it is
a [Readable][] stream.

For example:

```js
process.stdin.setEncoding('utf8');

2 changes: 0 additions & 2 deletions doc/api/querystring.md
Original file line number Diff line number Diff line change
@@ -108,8 +108,6 @@ It serializes the following types of values passed in `obj`:
{string|number|boolean|string[]|number[]|boolean[]}
Any other input values will be coerced to empty strings.

For example:

```js
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });
// returns 'foo=bar&baz=qux&baz=quux&corge='
Loading

0 comments on commit 9cb96ac

Please sign in to comment.