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>
  • Loading branch information
Trott authored and addaleax committed Feb 26, 2018
1 parent 38cf3cf commit 8532251
Show file tree
Hide file tree
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
Expand Up @@ -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"]
Expand Down
8 changes: 1 addition & 7 deletions doc/api/async_hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) => {});
```
Expand Down Expand Up @@ -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');

Expand All @@ -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) {
Expand All @@ -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
Expand Down
4 changes: 0 additions & 4 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -930,8 +930,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'));
// <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
Expand All @@ -940,8 +938,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]() {
Expand Down
2 changes: 0 additions & 2 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,8 +226,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);
Expand Down
6 changes: 0 additions & 6 deletions doc/api/dns.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
[
Expand Down Expand Up @@ -369,8 +367,6 @@ function will contain an array of objects with the following properties:
* `order`
* `preference`

For example:

<!-- eslint-skip -->
```js
{
Expand Down Expand Up @@ -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',
Expand Down
2 changes: 0 additions & 2 deletions doc/api/domain.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
11 changes: 2 additions & 9 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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"
Expand Down Expand Up @@ -1298,9 +1292,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
Expand Down
10 changes: 0 additions & 10 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');

Expand All @@ -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');

Expand Down Expand Up @@ -403,7 +399,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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1354,8 +1346,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
Expand Down
4 changes: 0 additions & 4 deletions doc/api/http2.md
Original file line number Diff line number Diff line change
Expand Up @@ -1094,8 +1094,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');
Expand Down Expand Up @@ -2008,8 +2006,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',
Expand Down
2 changes: 1 addition & 1 deletion doc/api/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```
Expand Down
2 changes: 0 additions & 2 deletions doc/api/os.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
[
Expand Down
10 changes: 0 additions & 10 deletions doc/api/path.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand All @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down
20 changes: 0 additions & 20 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}`);
Expand Down Expand Up @@ -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) => {
Expand Down Expand Up @@ -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`);
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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();
Expand Down Expand Up @@ -925,8 +915,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
```
Expand Down Expand Up @@ -955,8 +943,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'
Expand Down Expand Up @@ -1229,8 +1215,6 @@ group.
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.');
Expand Down Expand Up @@ -1506,8 +1490,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
{
Expand Down Expand Up @@ -1712,8 +1694,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');

Expand Down
2 changes: 0 additions & 2 deletions doc/api/querystring.md
Original file line number Diff line number Diff line change
Expand Up @@ -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='
Expand Down
Loading

0 comments on commit 8532251

Please sign in to comment.