From 7af680e6fe531e06792ae2c0dbdf8d7c5c7243c4 Mon Sep 17 00:00:00 2001 From: Daniel Bevenius Date: Tue, 8 Nov 2016 21:04:57 +0100 Subject: [PATCH] doc: make comment indentation consistent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently, some of the docs use different indentation for comments in the code examples. This commit makes the indentation consistent by putting the comments at the beginning of the line (really no indentation that is). PR-URL: https://github.com/nodejs/node/pull/9518 Reviewed-By: Teddy Katz Reviewed-By: Roman Reiss Reviewed-By: Michaël Zasso --- doc/api/addons.md | 42 ++++++++++------ doc/api/assert.md | 96 +++++++++++++++++++----------------- doc/api/buffer.md | 16 +++--- doc/api/console.md | 52 ++++++++++---------- doc/api/crypto.md | 30 ++++++------ doc/api/dns.md | 2 +- doc/api/errors.md | 2 +- doc/api/events.md | 62 +++++++++++------------ doc/api/fs.md | 26 +++++----- doc/api/globals.md | 4 +- doc/api/path.md | 64 ++++++++++++------------ doc/api/process.md | 10 ++-- doc/api/stream.md | 6 +-- doc/api/util.md | 120 ++++++++++++++++++++++----------------------- 14 files changed, 277 insertions(+), 255 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index 1dfdf8e3bb057a..d91f60ae7bf6ef 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -140,7 +140,8 @@ Once built, the binary Addon can be used from within Node.js by pointing // hello.js const addon = require('./build/Release/addon'); -console.log(addon.hello()); // 'world' +console.log(addon.hello()); +// Prints: 'world' ``` Please see the examples below for further information or @@ -372,7 +373,8 @@ To test it, run the following JavaScript: const addon = require('./build/Release/addon'); addon((msg) => { - console.log(msg); // 'hello world' + console.log(msg); +// Prints: 'hello world' }); ``` @@ -423,7 +425,8 @@ const addon = require('./build/Release/addon'); var obj1 = addon('hello'); var obj2 = addon('world'); -console.log(obj1.msg, obj2.msg); // 'hello world' +console.log(obj1.msg, obj2.msg); +// Prints: 'hello world' ``` @@ -480,7 +483,8 @@ To test: const addon = require('./build/Release/addon'); var fn = addon(); -console.log(fn()); // 'hello world' +console.log(fn()); +// Prints: 'hello world' ``` @@ -642,9 +646,12 @@ Test it with: const addon = require('./build/Release/addon'); var obj = new addon.MyObject(10); -console.log(obj.plusOne()); // 11 -console.log(obj.plusOne()); // 12 -console.log(obj.plusOne()); // 13 +console.log(obj.plusOne()); +// Prints: 11 +console.log(obj.plusOne()); +// Prints: 12 +console.log(obj.plusOne()); +// Prints: 13 ``` ### Factory of wrapped objects @@ -834,14 +841,20 @@ Test it with: const createObject = require('./build/Release/addon'); var obj = createObject(10); -console.log(obj.plusOne()); // 11 -console.log(obj.plusOne()); // 12 -console.log(obj.plusOne()); // 13 +console.log(obj.plusOne()); +// Prints: 11 +console.log(obj.plusOne()); +// Prints: 12 +console.log(obj.plusOne()); +// Prints: 13 var obj2 = createObject(20); -console.log(obj2.plusOne()); // 21 -console.log(obj2.plusOne()); // 22 -console.log(obj2.plusOne()); // 23 +console.log(obj2.plusOne()); +// Prints: 21 +console.log(obj2.plusOne()); +// Prints: 22 +console.log(obj2.plusOne()); +// Prints: 23 ``` @@ -1013,7 +1026,8 @@ var obj1 = addon.createObject(10); var obj2 = addon.createObject(20); var result = addon.add(obj1, obj2); -console.log(result); // 30 +console.log(result); +// Prints: 30 ``` ### AtExit hooks diff --git a/doc/api/assert.md b/doc/api/assert.md index ed7080323841fa..066a72215c658f 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -22,14 +22,16 @@ An alias of [`assert.ok()`][] . ```js const assert = require('assert'); -assert(true); // OK -assert(1); // OK +assert(true); +// OK +assert(1); +// OK assert(false); - // throws "AssertionError: false == true" +// throws "AssertionError: false == true" assert(0); - // throws "AssertionError: 0 == true" +// throws "AssertionError: 0 == true" assert(false, 'it\'s false'); - // throws "AssertionError: it's false" +// throws "AssertionError: it's false" ``` ## assert.deepEqual(actual, expected[, message]) @@ -75,18 +77,18 @@ const obj3 = { const obj4 = Object.create(obj1); assert.deepEqual(obj1, obj1); - // OK, object is equal to itself +// OK, object is equal to itself assert.deepEqual(obj1, obj2); - // AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } } - // values of b are different +// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } } +// values of b are different assert.deepEqual(obj1, obj3); - // OK, objects are equal +// OK, objects are equal assert.deepEqual(obj1, obj4); - // AssertionError: { a: { b: 1 } } deepEqual {} - // Prototypes are ignored +// AssertionError: { a: { b: 1 } } deepEqual {} +// Prototypes are ignored ``` If the values are not equal, an `AssertionError` is thrown with a `message` @@ -106,11 +108,11 @@ Second, object comparisons include a strict equality check of their prototypes. const assert = require('assert'); assert.deepEqual({a:1}, {a:'1'}); - // OK, because 1 == '1' +// OK, because 1 == '1' assert.deepStrictEqual({a:1}, {a:'1'}); - // AssertionError: { a: 1 } deepStrictEqual { a: '1' } - // because 1 !== '1' using strict equality +// AssertionError: { a: 1 } deepStrictEqual { a: '1' } +// because 1 !== '1' using strict equality ``` If the values are not equal, an `AssertionError` is thrown with a `message` @@ -184,14 +186,14 @@ using the equal comparison operator ( `==` ). const assert = require('assert'); assert.equal(1, 1); - // OK, 1 == 1 +// OK, 1 == 1 assert.equal(1, '1'); - // OK, 1 == '1' +// OK, 1 == '1' assert.equal(1, 2); - // AssertionError: 1 == 2 +// AssertionError: 1 == 2 assert.equal({a: {b: 1}}, {a: {b: 1}}); - //AssertionError: { a: { b: 1 } } == { a: { b: 1 } } +//AssertionError: { a: { b: 1 } } == { a: { b: 1 } } ``` If the values are not equal, an `AssertionError` is thrown with a `message` @@ -211,10 +213,10 @@ Otherwise, the error message is the value of `message`. const assert = require('assert'); assert.fail(1, 2, undefined, '>'); - // AssertionError: 1 > 2 +// AssertionError: 1 > 2 assert.fail(1, 2, 'whoops', '>'); - // AssertionError: whoops +// AssertionError: whoops ``` ## assert.ifError(value) @@ -228,10 +230,14 @@ argument in callbacks. ```js const assert = require('assert'); -assert.ifError(0); // OK -assert.ifError(1); // Throws 1 -assert.ifError('error'); // Throws 'error' -assert.ifError(new Error()); // Throws Error +assert.ifError(0); +// OK +assert.ifError(1); +// Throws 1 +assert.ifError('error'); +// Throws 'error' +assert.ifError(new Error()); +// Throws Error ``` ## assert.notDeepEqual(actual, expected[, message]) @@ -262,16 +268,16 @@ const obj3 = { const obj4 = Object.create(obj1); assert.notDeepEqual(obj1, obj1); - // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } +// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } assert.notDeepEqual(obj1, obj2); - // OK, obj1 and obj2 are not deeply equal +// OK, obj1 and obj2 are not deeply equal assert.notDeepEqual(obj1, obj3); - // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } +// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } assert.notDeepEqual(obj1, obj4); - // OK, obj1 and obj4 are not deeply equal +// OK, obj1 and obj2 are not deeply equal ``` If the values are deeply equal, an `AssertionError` is thrown with a `message` @@ -289,10 +295,10 @@ Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][]. const assert = require('assert'); assert.notDeepEqual({a:1}, {a:'1'}); - // AssertionError: { a: 1 } notDeepEqual { a: '1' } +// AssertionError: { a: 1 } notDeepEqual { a: '1' } assert.notDeepStrictEqual({a:1}, {a:'1'}); - // OK +// OK ``` If the values are deeply and strictly equal, an `AssertionError` is thrown @@ -311,13 +317,13 @@ Tests shallow, coercive inequality with the not equal comparison operator const assert = require('assert'); assert.notEqual(1, 2); - // OK +// OK assert.notEqual(1, 1); - // AssertionError: 1 != 1 +// AssertionError: 1 != 1 assert.notEqual(1, '1'); - // AssertionError: 1 != '1' +// AssertionError: 1 != '1' ``` If the values are equal, an `AssertionError` is thrown with a `message` @@ -336,13 +342,13 @@ Tests strict inequality as determined by the strict not equal operator const assert = require('assert'); assert.notStrictEqual(1, 2); - // OK +// OK assert.notStrictEqual(1, 1); - // AssertionError: 1 != 1 +// AssertionError: 1 != 1 assert.notStrictEqual(1, '1'); - // OK +// OK ``` If the values are strictly equal, an `AssertionError` is thrown with a @@ -364,14 +370,16 @@ parameter is `undefined`, a default error message is assigned. ```js const assert = require('assert'); -assert.ok(true); // OK -assert.ok(1); // OK +assert.ok(true); +// OK +assert.ok(1); +// OK assert.ok(false); - // throws "AssertionError: false == true" +// throws "AssertionError: false == true" assert.ok(0); - // throws "AssertionError: 0 == true" +// throws "AssertionError: 0 == true" assert.ok(false, 'it\'s false'); - // throws "AssertionError: it's false" +// throws "AssertionError: it's false" ``` ## assert.strictEqual(actual, expected[, message]) @@ -385,13 +393,13 @@ Tests strict equality as determined by the strict equality operator ( `===` ). const assert = require('assert'); assert.strictEqual(1, 2); - // AssertionError: 1 === 2 +// AssertionError: 1 === 2 assert.strictEqual(1, 1); - // OK +// OK assert.strictEqual(1, '1'); - // AssertionError: 1 === '1' +// AssertionError: 1 === '1' ``` If the values are not strictly equal, an `AssertionError` is thrown with a diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 810f06825fd087..093be3f09e9232 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -406,7 +406,7 @@ Example: ```js const buf = new Buffer(5); -// Prints (contents may vary): +// Prints: (contents may vary): console.log(buf); buf.fill(0); @@ -525,7 +525,7 @@ Example: ```js const buf = Buffer.allocUnsafe(5); -// Prints (contents may vary): +// Prints: (contents may vary): console.log(buf); buf.fill(0); @@ -1755,12 +1755,12 @@ Examples: ```js const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); -// Prints +// Prints: console.log(buf1); buf1.swap32(); -// Prints +// Prints: console.log(buf1); @@ -1785,12 +1785,12 @@ Examples: ```js const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); -// Prints +// Prints: console.log(buf1); buf1.swap64(); -// Prints +// Prints: console.log(buf1); @@ -2327,7 +2327,7 @@ sequence cannot be adequately represented in the target encoding. For instance: ```js const newBuf = buffer.transcode(Buffer.from('€'), 'utf8', 'ascii'); console.log(newBuf.toString('ascii')); - // prints '?' +// Prints: '?' ``` Because the Euro (`€`) sign is not representable in US-ASCII, it is replaced @@ -2397,7 +2397,7 @@ const SlowBuffer = require('buffer').SlowBuffer; const buf = new SlowBuffer(5); -// Prints (contents may vary): +// Prints: (contents may vary): console.log(buf); buf.fill(0); diff --git a/doc/api/console.md b/doc/api/console.md index 7b8d893197473f..054eacc2bc7f82 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -17,15 +17,15 @@ Example using the global `console`: ```js console.log('hello world'); - // Prints: hello world, to stdout +// Prints: hello world, to stdout console.log('hello %s', 'world'); - // Prints: hello world, to stdout +// Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); - // Prints: [Error: Whoops, something bad happened], to stderr +// Prints: [Error: Whoops, something bad happened], to stderr const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); - // Prints: Danger Will Robinson! Danger!, to stderr +// Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: @@ -36,15 +36,15 @@ const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); - // Prints: hello world, to out +// Prints: hello world, to out myConsole.log('hello %s', 'world'); - // Prints: hello world, to out +// Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); - // Prints: [Error: Whoops, something bad happened], to err +// Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); - // Prints: Danger Will Robinson! Danger!, to err +// Prints: Danger Will Robinson! Danger!, to err ``` While the API for the `Console` class is designed fundamentally around the @@ -111,9 +111,9 @@ using [`util.format()`][] and used as the error message. ```js console.assert(true, 'does nothing'); - // OK +// OK console.assert(false, 'Whoops %s', 'didn\'t work'); - // AssertionError: Whoops didn't work +// AssertionError: Whoops didn't work ``` *Note: the `console.assert()` method is implemented differently in Node.js @@ -190,9 +190,9 @@ values similar to `printf(3)` (the arguments are all passed to ```js const code = 5; console.error('error #%d', code); - // Prints: error #5, to stderr +// Prints: error #5, to stderr console.error('error', code); - // Prints: error 5, to stderr +// Prints: error 5, to stderr ``` If formatting elements (e.g. `%d`) are not found in the first string then @@ -219,9 +219,9 @@ values similar to `printf(3)` (the arguments are all passed to ```js var count = 5; console.log('count: %d', count); - // Prints: count: 5, to stdout +// Prints: count: 5, to stdout console.log('count:', count); - // Prints: count: 5, to stdout +// Prints: count: 5, to stdout ``` If formatting elements (e.g. `%d`) are not found in the first string then @@ -270,18 +270,18 @@ formatted message and stack trace to the current position in the code. ```js console.trace('Show me'); - // Prints: (stack trace will vary based on where trace is called) - // Trace: Show me - // at repl:2:9 - // at REPLServer.defaultEval (repl.js:248:27) - // at bound (domain.js:287:14) - // at REPLServer.runBound [as eval] (domain.js:300:12) - // at REPLServer. (repl.js:412:12) - // at emitOne (events.js:82:20) - // at REPLServer.emit (events.js:169:7) - // at REPLServer.Interface._onLine (readline.js:210:10) - // at REPLServer.Interface._line (readline.js:549:8) - // at REPLServer.Interface._ttyWrite (readline.js:826:14) +// Prints: (stack trace will vary based on where trace is called) +// Trace: Show me +// at repl:2:9 +// at REPLServer.defaultEval (repl.js:248:27) +// at bound (domain.js:287:14) +// at REPLServer.runBound [as eval] (domain.js:300:12) +// at REPLServer. (repl.js:412:12) +// at emitOne (events.js:82:20) +// at REPLServer.emit (events.js:169:7) +// at REPLServer.Interface._onLine (readline.js:210:10) +// at REPLServer.Interface._line (readline.js:549:8) +// at REPLServer.Interface._ttyWrite (readline.js:826:14) ``` ### console.warn([data][, ...args]) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 0f063157b7160a..7eddf0da2c1c81 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -15,8 +15,8 @@ const hash = crypto.createHmac('sha256', secret) .update('I love cupcakes') .digest('hex'); console.log(hash); - // Prints: - // c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e +// Prints: +// c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e ``` ## Determining if crypto support is unavailable @@ -73,7 +73,7 @@ const cert = require('crypto').Certificate(); const spkac = getSpkacSomehow(); const challenge = cert.exportChallenge(spkac); console.log(challenge.toString('utf8')); - // Prints the challenge as a UTF8 string +// Prints: the challenge as a UTF8 string ``` ### certificate.exportPublicKey(spkac) @@ -91,7 +91,7 @@ const cert = require('crypto').Certificate(); const spkac = getSpkacSomehow(); const publicKey = cert.exportPublicKey(spkac); console.log(publicKey); - // Prints the public key as +// Prints: the public key as ``` ### certificate.verifySpkac(spkac) @@ -106,7 +106,7 @@ The `spkac` argument must be a Node.js [`Buffer`][]. const cert = require('crypto').Certificate(); const spkac = getSpkacSomehow(); console.log(cert.verifySpkac(Buffer.from(spkac))); - // Prints true or false +// Prints: true or false ``` ## Class: Cipher @@ -169,7 +169,7 @@ const cipher = crypto.createCipher('aes192', 'a password'); var encrypted = cipher.update('some clear text data', 'utf8', 'hex'); encrypted += cipher.final('hex'); console.log(encrypted); - // Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504 +// Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504 ``` ### cipher.final([output_encoding]) @@ -304,7 +304,7 @@ var encrypted = 'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d81550 var decrypted = decipher.update(encrypted, 'hex', 'utf8'); decrypted += decipher.final('utf8'); console.log(decrypted); - // Prints: some clear text data +// Prints: some clear text data ``` ### decipher.final([output_encoding]) @@ -700,8 +700,8 @@ const hash = crypto.createHash('sha256'); hash.update('some data to hash'); console.log(hash.digest('hex')); - // Prints: - // 6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50 +// Prints: +// 6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50 ``` ### hash.digest([encoding]) @@ -783,8 +783,8 @@ const hmac = crypto.createHmac('sha256', 'a secret'); hmac.update('some data to hash'); console.log(hmac.digest('hex')); - // Prints: - // 7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e +// Prints: +// 7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e ``` ### hmac.digest([encoding]) @@ -839,7 +839,7 @@ sign.end(); const private_key = getPrivateKeySomehow(); console.log(sign.sign(private_key, 'hex')); - // Prints the calculated signature +// Prints: the calculated signature ``` Example: Using the [`sign.update()`][] and [`sign.sign()`][] methods: @@ -852,7 +852,7 @@ sign.update('some data to sign'); const private_key = getPrivateKeySomehow(); console.log(sign.sign(private_key, 'hex')); - // Prints the calculated signature +// Prints: the calculated signature ``` A `Sign` instance can also be created by just passing in the digest @@ -940,7 +940,7 @@ verify.end(); const public_key = getPublicKeySomehow(); const signature = getSignatureToVerify(); console.log(verify.verify(public_key, signature)); - // Prints true or false +// Prints: true or false ``` Example: Using the [`verify.update()`][] and [`verify.verify()`][] methods: @@ -954,7 +954,7 @@ verify.update('some data to sign'); const public_key = getPublicKeySomehow(); const signature = getSignatureToVerify(); console.log(verify.verify(public_key, signature)); - // Prints true or false +// Prints: true or false ``` ### verifier.update(data[, input_encoding]) diff --git a/doc/api/dns.md b/doc/api/dns.md index bfb0074e3c68e4..e930892cedc927 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -148,7 +148,7 @@ On error, `err` is an [`Error`][] object, where `err.code` is the error code. const dns = require('dns'); dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { console.log(hostname, service); - // Prints: localhost ssh + // Prints: localhost ssh }); ``` diff --git a/doc/api/errors.md b/doc/api/errors.md index 28f1858a1ded57..70588125a0f0c9 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -258,7 +258,7 @@ the stack trace of the `Error`, however changing this property after the ```js const err = new Error('The message'); console.log(err.message); - // Prints: The message +// Prints: The message ``` #### error.stack diff --git a/doc/api/events.md b/doc/api/events.md index 3cca1ada5b2efa..b468674c3613fa 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -51,12 +51,12 @@ listener is attached. const myEmitter = new MyEmitter(); myEmitter.on('event', function(a, b) { console.log(a, b, this); - // Prints: - // a b MyEmitter { - // domain: null, - // _events: { event: [Function] }, - // _eventsCount: 1, - // _maxListeners: undefined } + // Prints: + // a b MyEmitter { + // domain: null, + // _events: { event: [Function] }, + // _eventsCount: 1, + // _maxListeners: undefined } }); myEmitter.emit('event', 'a', 'b'); ``` @@ -68,7 +68,7 @@ the `this` keyword will no longer reference the `EventEmitter` instance: const myEmitter = new MyEmitter(); myEmitter.on('event', (a, b) => { console.log(a, b, this); - // Prints: a b {} + // Prints: a b {} }); myEmitter.emit('event', 'a', 'b'); ``` @@ -103,9 +103,9 @@ myEmitter.on('event', () => { console.log(++m); }); myEmitter.emit('event'); - // Prints: 1 +// Prints: 1 myEmitter.emit('event'); - // Prints: 2 +// Prints: 2 ``` Using the `eventEmitter.once()` method, it is possible to register a listener @@ -119,9 +119,9 @@ myEmitter.once('event', () => { console.log(++m); }); myEmitter.emit('event'); - // Prints: 1 +// Prints: 1 myEmitter.emit('event'); - // Ignored +// Ignored ``` ## Error events @@ -137,7 +137,7 @@ stack trace is printed, and the Node.js process exits. ```js const myEmitter = new MyEmitter(); myEmitter.emit('error', new Error('whoops!')); - // Throws and crashes Node.js +// Throws and crashes Node.js ``` To guard against crashing the Node.js process, a listener can be registered @@ -152,7 +152,7 @@ process.on('uncaughtException', (err) => { }); myEmitter.emit('error', new Error('whoops!')); - // Prints: whoops! there was an error +// Prints: whoops! there was an error ``` As a best practice, listeners should always be added for the `'error'` events. @@ -163,7 +163,7 @@ myEmitter.on('error', (err) => { console.log('whoops! there was an error'); }); myEmitter.emit('error', new Error('whoops!')); - // Prints: whoops! there was an error +// Prints: whoops! there was an error ``` ## Class: EventEmitter @@ -214,9 +214,9 @@ myEmitter.on('event', () => { console.log('A'); }); myEmitter.emit('event'); - // Prints: - // B - // A +// Prints: +// B +// A ``` ### Event: 'removeListener' @@ -245,7 +245,7 @@ const myEmitter = new MyEmitter(); myEmitter.on('event', () => {}); myEmitter.on('event', () => {}); console.log(EventEmitter.listenerCount(myEmitter, 'event')); - // Prints: 2 +// Prints: 2 ``` ### EventEmitter.defaultMaxListeners @@ -323,7 +323,7 @@ const sym = Symbol('symbol'); myEE.on(sym, () => {}); console.log(myEE.eventNames()); - // Prints [ 'foo', 'bar', Symbol(symbol) ] +// Prints: [ 'foo', 'bar', Symbol(symbol) ] ``` ### emitter.getMaxListeners() @@ -356,7 +356,7 @@ server.on('connection', (stream) => { console.log('someone connected!'); }); console.log(util.inspect(server.listeners('connection'))); - // Prints: [ [Function] ] +// Prints: [ [Function] ] ``` ### emitter.on(eventName, listener) @@ -390,9 +390,9 @@ const myEE = new EventEmitter(); myEE.on('foo', () => console.log('a')); myEE.prependListener('foo', () => console.log('b')); myEE.emit('foo'); - // Prints: - // b - // a +// Prints: +// b +// a ``` ### emitter.once(eventName, listener) @@ -423,9 +423,9 @@ const myEE = new EventEmitter(); myEE.once('foo', () => console.log('a')); myEE.prependOnceListener('foo', () => console.log('b')); myEE.emit('foo'); - // Prints: - // b - // a +// Prints: +// b +// a ``` ### emitter.prependListener(eventName, listener) @@ -530,15 +530,15 @@ myEmitter.on('event', callbackB); // callbackA removes listener callbackB but it will still be called. // Internal listener array at time of emit [callbackA, callbackB] myEmitter.emit('event'); - // Prints: - // A - // B +// Prints: +// A +// B // callbackB is now removed. // Internal listener array [callbackA] myEmitter.emit('event'); - // Prints: - // A +// Prints: +// A ``` diff --git a/doc/api/fs.md b/doc/api/fs.md index af1f2d6381e6c1..2786c64c2942be 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -918,7 +918,7 @@ For example, the following program retains only the first four bytes of the file ```js console.log(fs.readFileSync('temp.txt', 'utf8')); - // prints Node.js +// Prints: Node.js // get the file descriptor of the file to be truncated const fd = fs.openSync('temp.txt', 'r+'); @@ -928,7 +928,7 @@ fs.ftruncate(fd, 4, (err) => { assert.ifError(err); console.log(fs.readFileSync('temp.txt', 'utf8')); }); - // prints Node +// Prints: Node ``` If the file previously was shorter than `len` bytes, it is extended, and the @@ -936,7 +936,7 @@ extended part is filled with null bytes ('\0'). For example, ```js console.log(fs.readFileSync('temp.txt', 'utf-8')); - // prints Node.js +// Prints: Node.js // get the file descriptor of the file to be truncated const fd = fs.openSync('temp.txt', 'r+'); @@ -946,8 +946,8 @@ fs.ftruncate(fd, 10, (err) => { assert.ifError(!err); console.log(fs.readFileSync('temp.txt')); }); - // prints - // ('Node.js\0\0\0' in UTF8) +// Prints: +// ('Node.js\0\0\0' in UTF8) ``` The last three bytes are null bytes ('\0'), to compensate the over-truncation. @@ -1127,7 +1127,7 @@ Example: fs.mkdtemp('/tmp/foo-', (err, folder) => { if (err) throw err; console.log(folder); - // Prints: /tmp/foo-itXde2 + // Prints: /tmp/foo-itXde2 }); ``` @@ -1145,10 +1145,10 @@ const tmpDir = '/tmp'; fs.mkdtemp(tmpDir, (err, folder) => { if (err) throw err; console.log(folder); - // Will print something similar to `/tmpabc123`. - // Note that a new temporary directory is created - // at the file system root rather than *within* - // the /tmp directory. + // Will print something similar to `/tmpabc123`. + // Note that a new temporary directory is created + // at the file system root rather than *within* + // the /tmp directory. }); // This method is *CORRECT*: @@ -1156,9 +1156,9 @@ const path = require('path'); fs.mkdtemp(tmpDir + path.sep, (err, folder) => { if (err) throw err; console.log(folder); - // Will print something similar to `/tmp/abc123`. - // A new temporary directory is created within - // the /tmp directory. + // Will print something similar to `/tmp/abc123`. + // A new temporary directory is created within + // the /tmp directory. }); ``` diff --git a/doc/api/globals.md b/doc/api/globals.md index 885e2e09fc8879..ca96ec4478d6ca 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -35,7 +35,7 @@ Example: running `node example.js` from `/Users/mjr` ```js console.log(__dirname); -// /Users/mjr +// Prints: /Users/mjr ``` `__dirname` isn't actually a global but rather local to each module. @@ -68,7 +68,7 @@ Example: running `node example.js` from `/Users/mjr` ```js console.log(__filename); -// /Users/mjr/example.js +// Prints: /Users/mjr/example.js ``` `__filename` isn't actually a global but rather local to each module. diff --git a/doc/api/path.md b/doc/api/path.md index 45dac1069ce8c5..fdd3063e69bf81 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -24,14 +24,14 @@ On POSIX: ```js path.basename('C:\\temp\\myfile.html'); - // returns 'C:\temp\myfile.html' +// Returns: 'C:\temp\myfile.html' ``` On Windows: ```js path.basename('C:\\temp\\myfile.html'); - // returns 'myfile.html' +// Returns: 'myfile.html' ``` To achieve consistent results when working with Windows file paths on any @@ -41,7 +41,7 @@ On POSIX and Windows: ```js path.win32.basename('C:\\temp\\myfile.html'); - // returns 'myfile.html' +// Returns: 'myfile.html' ``` To achieve consistent results when working with POSIX file paths on any @@ -51,7 +51,7 @@ On POSIX and Windows: ```js path.posix.basename('/tmp/myfile.html'); - // returns 'myfile.html' +// Returns: 'myfile.html' ``` ## path.basename(path[, ext]) @@ -70,10 +70,10 @@ For example: ```js path.basename('/foo/bar/baz/asdf/quux.html') - // returns 'quux.html' +// Returns: 'quux.html' path.basename('/foo/bar/baz/asdf/quux.html', '.html') - // returns 'quux' +// Returns: 'quux' ``` A [`TypeError`][] is thrown if `path` is not a string or if `ext` is given @@ -95,20 +95,20 @@ For example, on POSIX: ```js console.log(process.env.PATH) -// '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin' +// Prints: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin' process.env.PATH.split(path.delimiter) -// returns ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin'] +// Returns: ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin'] ``` On Windows: ```js console.log(process.env.PATH) -// 'C:\Windows\system32;C:\Windows;C:\Program Files\node\' +// Prints: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\' process.env.PATH.split(path.delimiter) -// returns ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\'] +// Returns: ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\'] ``` ## path.dirname(path) @@ -126,7 +126,7 @@ For example: ```js path.dirname('/foo/bar/baz/asdf/quux') -// returns '/foo/bar/baz/asdf' +// Returns: '/foo/bar/baz/asdf' ``` A [`TypeError`][] is thrown if `path` is not a string. @@ -149,19 +149,19 @@ For example: ```js path.extname('index.html') -// returns '.html' +// Returns: '.html' path.extname('index.coffee.md') -// returns '.md' +// Returns: '.md' path.extname('index.') -// returns '.' +// Returns: '.' path.extname('index') -// returns '' +// Returns: '' path.extname('.index') -// returns '' +// Returns: '' ``` A [`TypeError`][] is thrown if `path` is not a string. @@ -205,7 +205,7 @@ path.format({ dir: '/home/user/dir', base: 'file.txt' }); -// returns '/home/user/dir/file.txt' +// Returns: '/home/user/dir/file.txt' // `root` will be used if `dir` is not specified. // If only `root` is provided or `dir` is equal to `root` then the @@ -214,7 +214,7 @@ path.format({ root: '/', base: 'file.txt' }); -// returns '/file.txt' +// Returns: '/file.txt' // `name` + `ext` will be used if `base` is not specified. path.format({ @@ -222,13 +222,13 @@ path.format({ name: 'file', ext: '.txt' }); -// returns '/file.txt' +// Returns: '/file.txt' // `base` will be returned if `dir` or `root` are not provided. path.format({ base: 'file.txt' }); -// returns 'file.txt' +// Returns: 'file.txt' ``` On Windows: @@ -241,7 +241,7 @@ path.format({ ext : ".txt", name : "file" }); -// returns 'C:\\path\\dir\\file.txt' +// Returns: 'C:\\path\\dir\\file.txt' ``` ## path.isAbsolute(path) @@ -298,7 +298,7 @@ For example: ```js path.join('/foo', 'bar', 'baz/asdf', 'quux', '..') -// returns '/foo/bar/baz/asdf' +// Returns: '/foo/bar/baz/asdf' path.join('foo', {}, 'bar') // throws TypeError: Arguments to path.join must be strings @@ -328,14 +328,14 @@ For example on POSIX: ```js path.normalize('/foo/bar//baz/asdf/quux/..') -// returns '/foo/bar/baz/asdf' +// Returns: '/foo/bar/baz/asdf' ``` On Windows: ```js path.normalize('C:\\temp\\\\foo\\bar\\..\\'); -// returns 'C:\\temp\\foo\\' +// Returns: 'C:\\temp\\foo\\' ``` A [`TypeError`][] is thrown if `path` is not a string. @@ -363,7 +363,7 @@ For example on POSIX: ```js path.parse('/home/user/dir/file.txt') -// returns +// Returns: // { // root : "/", // dir : "/home/user/dir", @@ -387,7 +387,7 @@ On Windows: ```js path.parse('C:\\path\\dir\\file.txt') -// returns +// Returns: // { // root : "C:\\", // dir : "C:\\path\\dir", @@ -439,14 +439,14 @@ For example on POSIX: ```js path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb') -// returns '../../impl/bbb' +// Returns: '../../impl/bbb' ``` On Windows: ```js path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb') -// returns '..\\..\\impl\\bbb' +// Returns: '..\\..\\impl\\bbb' ``` A [`TypeError`][] is thrown if neither `from` nor `to` is a string. @@ -482,10 +482,10 @@ For example: ```js path.resolve('/foo/bar', './baz') -// returns '/foo/bar/baz' +// Returns: '/foo/bar/baz' path.resolve('/foo/bar', '/tmp/file/') -// returns '/tmp/file' +// Returns: '/tmp/file' path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif') // if the current working directory is /home/myself/node, @@ -510,14 +510,14 @@ For example on POSIX: ```js 'foo/bar/baz'.split(path.sep) -// returns ['foo', 'bar', 'baz'] +// Returns: ['foo', 'bar', 'baz'] ``` On Windows: ```js 'foo\\bar\\baz'.split(path.sep) -// returns ['foo', 'bar', 'baz'] +// Returns: ['foo', 'bar', 'baz'] ``` ## path.win32 diff --git a/doc/api/process.md b/doc/api/process.md index 44db505eab8e04..18c23dda2de193 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -725,13 +725,13 @@ specific process warnings. These can be listened for by adding a handler to the ```js // Emit a warning using a string... process.emitWarning('Something happened!'); - // Emits: (node: 56338) Warning: Something happened! +// Emits: (node: 56338) Warning: Something happened! ``` ```js // Emit a warning using a string and a name... process.emitWarning('Something Happened!', 'CustomWarning'); - // Emits: (node:56338) CustomWarning: Something Happened! +// Emits: (node:56338) CustomWarning: Something Happened! ``` In each of the previous examples, an `Error` object is generated internally by @@ -756,7 +756,7 @@ const myWarning = new Error('Warning! Something happened!'); myWarning.name = 'CustomWarning'; process.emitWarning(myWarning); - // Emits: (node:56338) CustomWarning: Warning! Something Happened! +// Emits: (node:56338) CustomWarning: Warning! Something Happened! ``` A `TypeError` is thrown if `warning` is anything other than a string or `Error` @@ -789,9 +789,9 @@ function emitMyWarning() { } } emitMyWarning(); - // Emits: (node: 56339) Warning: Only warn once! +// Emits: (node: 56339) Warning: Only warn once! emitMyWarning(); - // Emits nothing +// Emits nothing ``` ## process.execArgv diff --git a/doc/api/stream.md b/doc/api/stream.md index cf31436f39f443..c3544f7939c4c0 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1696,11 +1696,11 @@ myTransform.setEncoding('ascii'); myTransform.on('data', (chunk) => console.log(chunk)); myTransform.write(1); - // Prints: 01 +// Prints: 01 myTransform.write(10); - // Prints: 0a +// Prints: 0a myTransform.write(100); - // Prints: 64 +// Prints: 64 ``` ### Implementing a Transform Stream diff --git a/doc/api/util.md b/doc/api/util.md index 57ed7269f68b87..3e4a4b1d39fd82 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -113,7 +113,7 @@ not replaced. ```js util.format('%s:%s', 'foo'); - // Returns 'foo:%s' +// Returns: 'foo:%s' ``` If there are more arguments passed to the `util.format()` method than the @@ -310,7 +310,7 @@ class Box { const box = new Box(true); util.inspect(box); - // "Box< true >" +// Returns: "Box< true >" ``` Custom `[util.inspect.custom](depth, opts)` functions typically return a string @@ -326,7 +326,7 @@ obj[util.inspect.custom] = function(depth) { }; util.inspect(obj); - // "{ bar: 'baz' }" +// Returns: "{ bar: 'baz' }" ``` A custom inspection method can alternatively be provided by exposing @@ -341,7 +341,7 @@ obj.inspect = function(depth) { }; util.inspect(obj); - // "{ bar: 'baz' }" +// Returns: "{ bar: 'baz' }" ``` ### util.inspect.defaultOptions @@ -419,11 +419,11 @@ Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`. const util = require('util'); util.isArray([]); - // true +// Returns: true util.isArray(new Array); - // true +// Returns: true util.isArray({}); - // false +// Returns: false ``` ### util.isBoolean(object) @@ -442,11 +442,11 @@ Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`. const util = require('util'); util.isBoolean(1); - // false +// Returns: false util.isBoolean(0); - // false +// Returns: false util.isBoolean(false); - // true +// Returns: true ``` ### util.isBuffer(object) @@ -465,11 +465,11 @@ Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`. const util = require('util'); util.isBuffer({ length: 0 }); - // false +// Returns: false util.isBuffer([]); - // false +// Returns: false util.isBuffer(Buffer.from('hello world')); - // true +// Returns: true ``` ### util.isDate(object) @@ -488,11 +488,11 @@ Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`. const util = require('util'); util.isDate(new Date()); - // true +// Returns: true util.isDate(Date()); - // false (without 'new' returns a String) +// false (without 'new' returns a String) util.isDate({}); - // false +// Returns: false ``` ### util.isError(object) @@ -512,11 +512,11 @@ Returns `true` if the given `object` is an [`Error`][]. Otherwise, returns const util = require('util'); util.isError(new Error()); - // true +// Returns: true util.isError(new TypeError()); - // true +// Returns: true util.isError({ name: 'Error', message: 'an error occurred' }); - // false +// Returns: false ``` Note that this method relies on `Object.prototype.toString()` behavior. It is @@ -528,10 +528,10 @@ const util = require('util'); const obj = { name: 'Error', message: 'an error occurred' }; util.isError(obj); - // false +// Returns: false obj[Symbol.toStringTag] = 'Error'; util.isError(obj); - // true +// Returns: true ``` ### util.isFunction(object) @@ -554,11 +554,11 @@ function Foo() {} const Bar = function() {}; util.isFunction({}); - // false +// Returns: false util.isFunction(Foo); - // true +// Returns: true util.isFunction(Bar); - // true +// Returns: true ``` ### util.isNull(object) @@ -578,11 +578,11 @@ Returns `true` if the given `object` is strictly `null`. Otherwise, returns const util = require('util'); util.isNull(0); - // false +// Returns: false util.isNull(undefined); - // false +// Returns: false util.isNull(null); - // true +// Returns: true ``` ### util.isNullOrUndefined(object) @@ -602,11 +602,11 @@ returns `false`. const util = require('util'); util.isNullOrUndefined(0); - // false +// Returns: false util.isNullOrUndefined(undefined); - // true +// Returns: true util.isNullOrUndefined(null); - // true +// Returns: true ``` ### util.isNumber(object) @@ -625,13 +625,13 @@ Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`. const util = require('util'); util.isNumber(false); - // false +// Returns: false util.isNumber(Infinity); - // true +// Returns: true util.isNumber(0); - // true +// Returns: true util.isNumber(NaN); - // true +// Returns: true ``` ### util.isObject(object) @@ -651,13 +651,13 @@ Returns `true` if the given `object` is strictly an `Object` **and** not a const util = require('util'); util.isObject(5); - // false +// Returns: false util.isObject(null); - // false +// Returns: false util.isObject({}); - // true +// Returns: true util.isObject(function(){}); - // false +// Returns: false ``` ### util.isPrimitive(object) @@ -677,23 +677,23 @@ Returns `true` if the given `object` is a primitive type. Otherwise, returns const util = require('util'); util.isPrimitive(5); - // true +// Returns: true util.isPrimitive('foo'); - // true +// Returns: true util.isPrimitive(false); - // true +// Returns: true util.isPrimitive(null); - // true +// Returns: true util.isPrimitive(undefined); - // true +// Returns: true util.isPrimitive({}); - // false +// Returns: false util.isPrimitive(function() {}); - // false +// Returns: false util.isPrimitive(/^$/); - // false +// Returns: false util.isPrimitive(new Date()); - // false +// Returns: false ``` ### util.isRegExp(object) @@ -712,11 +712,11 @@ Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`. const util = require('util'); util.isRegExp(/some regexp/); - // true +// Returns: true util.isRegExp(new RegExp('another regexp')); - // true +// Returns: true util.isRegExp({}); - // false +// Returns: false ``` ### util.isString(object) @@ -735,13 +735,13 @@ Returns `true` if the given `object` is a `string`. Otherwise, returns `false`. const util = require('util'); util.isString(''); - // true +// Returns: true util.isString('foo'); - // true +// Returns: true util.isString(String('foo')); - // true +// Returns: true util.isString(5); - // false +// Returns: false ``` ### util.isSymbol(object) @@ -760,11 +760,11 @@ Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`. const util = require('util'); util.isSymbol(5); - // false +// Returns: false util.isSymbol('foo'); - // false +// Returns: false util.isSymbol(Symbol('foo')); - // true +// Returns: true ``` ### util.isUndefined(object) @@ -784,11 +784,11 @@ const util = require('util'); const foo = undefined; util.isUndefined(5); - // false +// Returns: false util.isUndefined(foo); - // true +// Returns: true util.isUndefined(null); - // false +// Returns: false ``` ### util.log(string)