From d57fcec95188384b5fb5fde59a5b1b3b198d91bb Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 20 Feb 2018 15:10:10 -0800 Subject: [PATCH] doc: remove extraneous "for example" text 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: https://github.com/nodejs/node/pull/18890 Reviewed-By: Luigi Pinca Reviewed-By: Matheus Marchini Reviewed-By: Ruben Bridgewater Reviewed-By: Vse Mozhet Byt --- doc/api/addons.md | 2 +- doc/api/async_hooks.md | 8 +------- doc/api/buffer.md | 4 ---- doc/api/child_process.md | 2 -- doc/api/dns.md | 6 ------ doc/api/domain.md | 2 -- doc/api/errors.md | 11 ++--------- doc/api/fs.md | 10 ---------- doc/api/http2.md | 4 ---- doc/api/modules.md | 2 +- doc/api/n-api.md | 4 ++-- doc/api/os.md | 2 -- doc/api/path.md | 10 ---------- doc/api/process.md | 20 -------------------- doc/api/querystring.md | 2 -- doc/api/readline.md | 14 -------------- doc/api/repl.md | 2 +- doc/api/stream.md | 12 ------------ doc/api/util.md | 10 ++-------- doc/api/v8.md | 4 ---- doc/guides/using-internal-errors.md | 2 -- doc/guides/writing-tests.md | 6 ++---- 22 files changed, 12 insertions(+), 127 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index 385f64d955266e..ba98d8f5eb2aee 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -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"] diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 1b1dfa119b7abf..904c32acdc60a3 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -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 diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 82628156bf31eb..e1911d67146737 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -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: @@ -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]() { diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 80b74929b03fdb..ac794e6a23fe63 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -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); diff --git a/doc/api/dns.md b/doc/api/dns.md index c1ec1cfa51c41c..cda4823e3ce0e7 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -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: - ```js [ @@ -369,8 +367,6 @@ function will contain an array of objects with the following properties: * `order` * `preference` -For example: - ```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', diff --git a/doc/api/domain.md b/doc/api/domain.md index 77eff3a194238b..b303b0fdeb1746 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -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'); diff --git a/doc/api/errors.md b/doc/api/errors.md index dfd3a84d4746ad..c2475df1eb7399 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -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. ### 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])`. ### ERR_OUT_OF_RANGE diff --git a/doc/api/fs.md b/doc/api/fs.md index b0cba330c514bc..5062f76ff134aa 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -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 diff --git a/doc/api/http2.md b/doc/api/http2.md index 8eb92c9555a17a..78e4d9609af7cf 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -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', diff --git a/doc/api/modules.md b/doc/api/modules.md index be45991f1dd343..2930f2af68e095 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -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`: ```js diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 6f4924fcae9161..8da4c3e2d5462a 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -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 ``` diff --git a/doc/api/os.md b/doc/api/os.md index b5ecab0132305e..16ec5714e3f740 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -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: - ```js [ diff --git a/doc/api/path.md b/doc/api/path.md index 42824322b83f66..5cfeba53402e10 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -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' diff --git a/doc/api/process.md b/doc/api/process.md index 400cd26a123581..8209a07d72853a 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -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: - ```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: - ```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'); diff --git a/doc/api/querystring.md b/doc/api/querystring.md index 48412b01b94f88..cbf503af916593 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -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=' diff --git a/doc/api/readline.md b/doc/api/readline.md index 2e6c9cb07f7821..69c49b10ea4966 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -75,8 +75,6 @@ presses the ``, or `` keys. The listener function is called with a string containing the single line of received input. -For example: - ```js rl.on('line', (input) => { console.log(`Received: ${input}`); @@ -96,8 +94,6 @@ The `'pause'` event is emitted when one of the following occur: The listener function is called without passing any arguments. -For example: - ```js rl.on('pause', () => { console.log('Readline paused.'); @@ -133,8 +129,6 @@ not be emitted. The listener function is invoked without passing any arguments. -For example: - ```js rl.on('SIGCONT', () => { // `prompt` will automatically resume the stream @@ -156,8 +150,6 @@ event will be emitted. The listener function is invoked without passing any arguments. -For example: - ```js rl.on('SIGINT', () => { rl.question('Are you sure you want to exit? ', (answer) => { @@ -184,8 +176,6 @@ paused before the process was sent to the background. The listener function is invoked without passing any arguments. -For example: - ```js rl.on('SIGTSTP', () => { // This will override SIGTSTP and prevent the program from going to the @@ -307,8 +297,6 @@ paused. If the `readline.Interface` was created with `output` set to `null` or `undefined` the `data` and `key` are not written. -For example: - ```js rl.write('Delete this!'); // Simulate Ctrl+u to delete the line written previously @@ -387,8 +375,6 @@ changes: The `readline.createInterface()` method creates a new `readline.Interface` instance. -For example: - ```js const readline = require('readline'); const rl = readline.createInterface({ diff --git a/doc/api/repl.md b/doc/api/repl.md index 182c0434c0340a..916d6bd0e28818 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -96,7 +96,7 @@ are declared at the global scope. The default evaluator provides access to any variables that exist in the global scope. It is possible to expose a variable to the REPL explicitly by assigning -it to the `context` object associated with each `REPLServer`. For example: +it to the `context` object associated with each `REPLServer`: ```js const repl = require('repl'); diff --git a/doc/api/stream.md b/doc/api/stream.md index 20eaa95bc19ab4..85afb631aed175 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1148,8 +1148,6 @@ It will rarely be necessary to use `readable.wrap()` but the method has been provided as a convenience for interacting with older Node.js applications and libraries. -For example: - ```js const { OldReader } = require('./old-api-module.js'); const { Readable } = require('stream'); @@ -1352,8 +1350,6 @@ inheritance. This can be accomplished by directly creating instances of the `stream.Writable`, `stream.Readable`, `stream.Duplex` or `stream.Transform` objects and passing appropriate methods as constructor options. -For example: - ```js const { Writable } = require('stream'); @@ -1395,8 +1391,6 @@ constructor and implement the `writable._write()` method. The * `final` {Function} Implementation for the [`stream._final()`][stream-_final] method. -For example: - ```js const { Writable } = require('stream'); @@ -1645,8 +1639,6 @@ constructor and implement the `readable._read()` method. * `destroy` {Function} Implementation for the [`stream._destroy()`][readable-_destroy] method. -For example: - ```js const { Readable } = require('stream'); @@ -1903,8 +1895,6 @@ changes: * `writableHighWaterMark` {number} Sets `highWaterMark` for the writable side of the stream. Has no effect if `highWaterMark` is provided. -For example: - ```js const { Duplex } = require('stream'); @@ -2059,8 +2049,6 @@ on the Readable side is not consumed. * `flush` {Function} Implementation for the [`stream._flush()`][stream-_flush] method. -For example: - ```js const { Transform } = require('stream'); diff --git a/doc/api/util.md b/doc/api/util.md index 2ad5a6f3365cf1..dd5620c4808be3 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -26,8 +26,6 @@ a `(err, value) => ...` callback as the last argument. In the callback, the first argument will be the rejection reason (or `null` if the Promise resolved), and the second argument will be the resolved value. -For example: - ```js const util = require('util'); @@ -84,8 +82,6 @@ environment variable. If the `section` name appears within the value of that environment variable, then the returned function operates similar to [`console.error()`][]. If not, then the returned function is a no-op. -For example: - ```js const util = require('util'); const debuglog = util.debuglog('foo'); @@ -103,7 +99,7 @@ FOO 3245: hello from foo [123] where `3245` is the process id. If it is not run with that environment variable set, then it will not print anything. -The `section` supports wildcard also, for example: +The `section` supports wildcard also: ```js const util = require('util'); const debuglog = util.debuglog('foo-bar'); @@ -117,7 +113,7 @@ FOO-BAR 3257: hi there, it's foo-bar [2333] ``` Multiple comma-separated `section` names may be specified in the `NODE_DEBUG` -environment variable. For example: `NODE_DEBUG=fs,net,tls`. +environment variable: `NODE_DEBUG=fs,net,tls`. ## util.deprecate(fn, msg[, code]) ```js { diff --git a/doc/guides/using-internal-errors.md b/doc/guides/using-internal-errors.md index 90962757bb0bb2..c03f44623a0f7f 100644 --- a/doc/guides/using-internal-errors.md +++ b/doc/guides/using-internal-errors.md @@ -99,8 +99,6 @@ special cases, they should only validate that the expected code is received and NOT validate the message. This will reduce the amount of test change required when the message for an error changes. -For example: - ```js assert.throws(() => { socket.bind(); diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index 949aea402db5c8..aa4412e1613c2c 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -127,7 +127,7 @@ explanation go [here](https://github.com/nodejs/testing/issues/27). In the event a test needs a timer, consider using the `common.platformTimeout()` method. It allows setting specific timeouts -depending on the platform. For example: +depending on the platform: ```javascript const timer = setTimeout(fail, common.platformTimeout(4000)); @@ -259,9 +259,7 @@ features in JavaScript code in the `lib` directory. However, when writing tests, for the ease of backporting, it is encouraged to use those ES.Next features that can be used directly without a flag in [all maintained branches][]. [node.green][] lists available features -in each release. - -For example: +in each release, such as: - `let` and `const` over `var` - Template literals over string concatenation