diff --git a/doc/api/addons.md b/doc/api/addons.md index 1dfdf8e3bb..d91f60ae7b 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 ed70803238..066a72215c 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 810f06825f..093be3f09e 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 7b8d893197..054eacc2bc 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 0f063157b7..7eddf0da2c 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 bfb0074e3c..e930892ced 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 28f1858a1d..70588125a0 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 3cca1ada5b..b468674c36 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 20c0a38b96..10170dbf89 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 885e2e09fc..ca96ec4478 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 45dac1069c..fdd3063e69 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 44db505eab..18c23dda2d 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 cf31436f39..c3544f7939 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 57ed7269f6..3e4a4b1d39 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)