tools: capitalize sentences

This adds the `capitalized-comments` eslint rule to verify that
actual sentences use capital letters as starting letters. It ignores
special words and all lines below 62 characters.

.eslintrc.js

@@ -58,6 +58,18 @@ module.exports = {
     'arrow-spacing': ['error', { before: true, after: true }],
     'block-spacing': 'error',
     'brace-style': ['error', '1tbs', { allowSingleLine: true }],
+    'capitalized-comments': ['error', 'always', {
+      line: {
+        // Ignore all lines that have less characters than 62 and all lines that
+        // start with something that looks like a variable name or code.
+        ignorePattern: '^.{0,62}$|^ [a-z]+ ?[0-9A-Z_.(/=:-]',
+        ignoreInlineComments: true,
+        ignoreConsecutiveComments: true
+      },
+      block: {
+        ignorePattern: '.*'
+      }
+    }],
     'comma-dangle': ['error', 'only-multiline'],
     'comma-spacing': 'error',
     'comma-style': 'error',

benchmark/_cli.js

@@ -49,7 +49,7 @@ function CLI(usage, settings) {
         this.optional[currentOptional] = true;
         mode = 'both';
       } else {
-        // expect the next value to be option related (either -- or the value)
+        // Expect the next value to be option related (either -- or the value)
         mode = 'option';
       }
     } else if (mode === 'option') {

benchmark/child_process/child-process-exec-stdout.js

@@ -31,7 +31,7 @@ function childProcessExecStdout({ dur, len }) {
       try {
         execSync(`taskkill /f /t /pid ${child.pid}`);
       } catch {
-        // this is a best effort kill. stderr is piped to parent for tracing.
+        // This is a best effort kill. stderr is piped to parent for tracing.
       }
     } else {
       child.kill();

benchmark/common.js

@@ -146,7 +146,7 @@ Benchmark.prototype._run = function() {
   (function recursive(queueIndex) {
     const config = self.queue[queueIndex];
 
-    // set NODE_RUN_BENCHMARK_FN to indicate that the child shouldn't construct
+    // Set NODE_RUN_BENCHMARK_FN to indicate that the child shouldn't construct
     // a configuration queue, but just execute the benchmark function.
     const childEnv = Object.assign({}, process.env);
     childEnv.NODE_RUN_BENCHMARK_FN = '';
@@ -187,7 +187,7 @@ Benchmark.prototype.start = function() {
 };
 
 Benchmark.prototype.end = function(operations) {
-  // get elapsed time now and do error checking later for accuracy.
+  // Get elapsed time now and do error checking later for accuracy.
   const elapsed = process.hrtime(this._time);
 
   if (!this._started) {

benchmark/crypto/cipher-stream.js

@@ -58,7 +58,7 @@ function main({ api, cipher, type, len, writes }) {
 
   const fn = api === 'stream' ? streamWrite : legacyWrite;
 
-  // write data as fast as possible to alice, and have bob decrypt.
+  // Write data as fast as possible to alice, and have bob decrypt.
   // use old API for comparison to v0.8
   bench.start();
   fn(alice_cipher, bob_cipher, message, encoding, writes);

benchmark/dgram/array-vs-concat.js

@@ -1,4 +1,4 @@
-// test UDP send throughput with the multi buffer API against Buffer.concat
+// Test UDP send throughput with the multi buffer API against Buffer.concat
 'use strict';
 
 const common = require('../common.js');

benchmark/dgram/offset-length.js

@@ -1,4 +1,4 @@
-// test UDP send/recv throughput with the "old" offset/length API
+// Test UDP send/recv throughput with the "old" offset/length API
 'use strict';
 
 const common = require('../common.js');

benchmark/napi/function_call/index.js

@@ -7,7 +7,7 @@
 const assert = require('assert');
 const common = require('../../common.js');
 
-// this fails when we try to open with a different version of node,
+// This fails when we try to open with a different version of node,
 // which is quite common for benchmarks.  so in that case, just
 // abort quietly.
 

benchmark/net/net-wrap-js-stream-passthrough.js

@@ -1,4 +1,4 @@
-// test the speed of .pipe() with JSStream wrapping for PassThrough streams
+// Test the speed of .pipe() with JSStream wrapping for PassThrough streams
 'use strict';
 
 const common = require('../common.js');

doc/api/async_hooks.md

@@ -61,12 +61,12 @@ asyncHook.disable();
 // resource referenced by "asyncId" may not have been populated.
 function init(asyncId, type, triggerAsyncId, resource) { }
 
-// before is called just before the resource's callback is called. It can be
+// Before is called just before the resource's callback is called. It can be
 // called 0-N times for handles (e.g. TCPWrap), and will be called exactly 1
 // time for requests (e.g. FSReqCallback).
 function before(asyncId) { }
 
-// after is called just after the resource's callback has finished.
+// After is called just after the resource's callback has finished.
 function after(asyncId) { }
 
 // destroy is called when an AsyncWrap instance is destroyed.
@@ -159,7 +159,7 @@ const fs = require('fs');
 const util = require('util');
 
 function debug(...args) {
-  // use a function like this one when debugging inside an AsyncHooks callback
+  // Use a function like this one when debugging inside an AsyncHooks callback
   fs.writeFileSync('log.out', `${util.format(...args)}\n`, { flag: 'a' });
 }
 ```

doc/api/crypto.md

@@ -772,7 +772,7 @@ const uncompressedKey = ECDH.convertKey(compressedKey,
                                         'hex',
                                         'uncompressed');
 
-// the converted key and the uncompressed public key should be the same
+// The converted key and the uncompressed public key should be the same
 console.log(uncompressedKey === ecdh.getPublicKey('hex'));
 ```
 

doc/api/domain.md

@@ -143,7 +143,7 @@ if (cluster.isMaster) {
         // a new worker.
         cluster.worker.disconnect();
 
-        // try to send an error to the request that triggered the problem
+        // Try to send an error to the request that triggered the problem
         res.statusCode = 500;
         res.setHeader('content-type', 'text/plain');
         res.end('Oops, there was a problem!\n');

doc/api/errors.md

@@ -371,7 +371,7 @@ range, or outside the set of options for a given function parameter.
 
 ```js
 require('net').connect(-1);
-// throws "RangeError: "port" option should be >= 0 and < 65536: -1"
+// Throws "RangeError: "port" option should be >= 0 and < 65536: -1"
 ```
 
 Node.js will generate and throw `RangeError` instances *immediately* as a form
@@ -388,7 +388,7 @@ will do so.
 
 ```js
 doesNotExist;
-// throws ReferenceError, doesNotExist is not a variable in this program.
+// Throws ReferenceError, doesNotExist is not a variable in this program.
 ```
 
 Unless an application is dynamically generating and running code,

doc/api/events.md

@@ -638,14 +638,14 @@ emitter.once('log', () => console.log('log once'));
 const listeners = emitter.rawListeners('log');
 const logFnWrapper = listeners[0];
 
-// logs "log once" to the console and does not unbind the `once` event
+// Logs "log once" to the console and does not unbind the `once` event
 logFnWrapper.listener();
 
 // logs "log once" to the console and removes the listener
 logFnWrapper();
 
 emitter.on('log', () => console.log('log persistently'));
-// will return a new Array with a single function bound by `.on()` above
+// Will return a new Array with a single function bound by `.on()` above
 const newListeners = emitter.rawListeners('log');
 
 // logs "log persistently" twice

doc/api/fs.md

@@ -1926,7 +1926,7 @@ console.log(fs.readFileSync('temp.txt', 'utf8'));
 // get the file descriptor of the file to be truncated
 const fd = fs.openSync('temp.txt', 'r+');
 
-// truncate the file to 10 bytes, whereas the actual size is 7 bytes
+// Truncate the file to 10 bytes, whereas the actual size is 7 bytes
 fs.ftruncate(fd, 10, (err) => {
   assert.ifError(err);
   console.log(fs.readFileSync('temp.txt'));

doc/api/modules.md

@@ -49,7 +49,7 @@ console.log(`The area of mySquare is ${mySquare.area()}`);
 The `square` module is defined in `square.js`:
 
 ```js
-// assigning to exports will not modify module, must use module.exports
+// Assigning to exports will not modify module, must use module.exports
 module.exports = class Square {
   constructor(width) {
     this.width = width;

doc/api/process.md

@@ -286,7 +286,7 @@ The listener function is called with the following arguments:
 ```js
 process.on('unhandledRejection', (reason, p) => {
   console.log('Unhandled Rejection at:', p, 'reason:', reason);
-  // application specific logging, throwing an error, or other logic here
+  // Application specific logging, throwing an error, or other logic here
 });
 
 somePromise.then((res) => {

doc/api/stream.md

@@ -131,7 +131,7 @@ const server = http.createServer((req, res) => {
     body += chunk;
   });
 
-  // the 'end' event indicates that the entire body has been received
+  // The 'end' event indicates that the entire body has been received
   req.on('end', () => {
     try {
       const data = JSON.parse(body);

doc/api/util.md

@@ -159,7 +159,7 @@ const util = require('util');
 const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
 const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
 fn1(); // emits a deprecation warning with code DEP0001
-fn2(); // does not emit a deprecation warning because it has the same code
+fn2(); // Does not emit a deprecation warning because it has the same code
 ```
 
 If either the `--no-deprecation` or `--no-warnings` command line flags are

doc/api/worker_threads.md

@@ -109,7 +109,7 @@ const { MessageChannel } = require('worker_threads');
 const { port1, port2 } = new MessageChannel();
 port1.on('message', (message) => console.log('received', message));
 port2.postMessage({ foo: 'bar' });
-// prints: received { foo: 'bar' } from the `port1.on('message')` listener
+// Prints: received { foo: 'bar' } from the `port1.on('message')` listener
 ```
 
 ## Class: MessagePort

lib/_http_agent.js

@@ -50,7 +50,7 @@ function Agent(options) {
 
   this.options = util._extend({}, options);
 
-  // don't confuse net and make it think that we're connecting to a pipe
+  // Don't confuse net and make it think that we're connecting to a pipe
   this.options.path = null;
   this.requests = {};
   this.sockets = {};

lib/_http_outgoing.js

@@ -388,7 +388,7 @@ function _storeHeader(firstLine, headers) {
   this._header = header + CRLF;
   this._headerSent = false;
 
-  // wait until the first body chunk, or close(), is sent to flush,
+  // Wait until the first body chunk, or close(), is sent to flush,
   // UNLESS we're sending Expect: 100-continue.
   if (state.expect) this._send('');
 }

lib/_http_server.js

@@ -263,7 +263,7 @@ function writeHead(statusCode, reason, obj) {
     this._hasBody = false;
   }
 
-  // don't keep alive connections where the client expects 100 Continue
+  // Don't keep alive connections where the client expects 100 Continue
   // but we sent a final status; they may put extra bytes on the wire.
   if (this._expect_continue && !this._sent100) {
     this.shouldKeepAlive = false;

lib/_stream_readable.js

@@ -86,7 +86,7 @@ function ReadableState(options, stream, isDuplex) {
   if (isDuplex)
     this.objectMode = this.objectMode || !!options.readableObjectMode;
 
-  // the point at which it stops calling _read() to fill the buffer
+  // The point at which it stops calling _read() to fill the buffer
   // Note: 0 is a valid value, means "don't call _read preemptively ever"
   this.highWaterMark = getHighWaterMark(this, options, 'readableHighWaterMark',
                                         isDuplex);
@@ -103,7 +103,7 @@ function ReadableState(options, stream, isDuplex) {
   this.endEmitted = false;
   this.reading = false;
 
-  // a flag to be able to tell if the event 'readable'/'data' is emitted
+  // A flag to be able to tell if the event 'readable'/'data' is emitted
   // immediately, or on a later tick.  We set this to true at first, because
   // any actions that shouldn't happen until "later" should generally also
   // not happen before the first read call.
@@ -131,7 +131,7 @@ function ReadableState(options, stream, isDuplex) {
   // Everything else in the universe uses 'utf8', though.
   this.defaultEncoding = options.defaultEncoding || 'utf8';
 
-  // the number of writers that are awaiting a drain event in .pipe()s
+  // The number of writers that are awaiting a drain event in .pipe()s
   this.awaitDrain = 0;
 
   // if true, a maybeReadMore has been scheduled
@@ -374,7 +374,7 @@ function howMuchToRead(n, state) {
   return state.length;
 }
 
-// you can override either this method, or the async _read(n) below.
+// You can override either this method, or the async _read(n) below.
 Readable.prototype.read = function(n) {
   debug('read', n);
   n = parseInt(n, 10);
@@ -436,13 +436,13 @@ Readable.prototype.read = function(n) {
   var doRead = state.needReadable;
   debug('need readable', doRead);
 
-  // if we currently have less than the highWaterMark, then also read some
+  // If we currently have less than the highWaterMark, then also read some
   if (state.length === 0 || state.length - n < state.highWaterMark) {
     doRead = true;
     debug('length less than watermark', doRead);
   }
 
-  // however, if we've ended, then there's no point, and if we're already
+  // However, if we've ended, then there's no point, and if we're already
   // reading, then it's unnecessary.
   if (state.ended || state.reading) {
     doRead = false;
@@ -451,7 +451,7 @@ Readable.prototype.read = function(n) {
     debug('do read');
     state.reading = true;
     state.sync = true;
-    // if the length is currently zero, then we *need* a readable event.
+    // If the length is currently zero, then we *need* a readable event.
     if (state.length === 0)
       state.needReadable = true;
     // call internal read method
@@ -554,7 +554,7 @@ function emitReadable_(stream) {
 }
 
 
-// at this point, the user has presumably seen the 'readable' event,
+// At this point, the user has presumably seen the 'readable' event,
 // and called read() to consume some data.  that may have triggered
 // in turn another _read(n) call, in which case reading = true if
 // it's in progress.
@@ -582,7 +582,7 @@ function maybeReadMore_(stream, state) {
   state.readingMore = false;
 }
 
-// abstract method.  to be overridden in specific implementation classes.
+// Abstract method.  to be overridden in specific implementation classes.
 // call cb(er, data) where data is <= n in length.
 // for virtual (non-string, non-buffer) streams, "length" is somewhat
 // arbitrary, and perhaps not very meaningful.

lib/_stream_transform.js

@@ -116,10 +116,10 @@ function Transform(options) {
     writeencoding: null
   };
 
-  // start out asking for a readable event once data is transformed.
+  // Start out asking for a readable event once data is transformed.
   this._readableState.needReadable = true;
 
-  // we have implemented the _read method, and done the other things
+  // We have implemented the _read method, and done the other things
   // that Readable wants before the first _read call, so unset the
   // sync guard flag.
   this._readableState.sync = false;

lib/_stream_writable.js

@@ -90,7 +90,7 @@ function WritableState(options, stream, isDuplex) {
   // has it been destroyed
   this.destroyed = false;
 
-  // should we decode strings into buffers before passing to _write?
+  // Should we decode strings into buffers before passing to _write?
   // this is here so that some node-core streams can optimize string
   // handling at a lower level.
   var noDecode = options.decodeStrings === false;
@@ -112,21 +112,21 @@ function WritableState(options, stream, isDuplex) {
   // when true all writes will be buffered until .uncork() call
   this.corked = 0;
 
-  // a flag to be able to tell if the onwrite cb is called immediately,
+  // A flag to be able to tell if the onwrite cb is called immediately,
   // or on a later tick.  We set this to true at first, because any
   // actions that shouldn't happen until "later" should generally also
   // not happen before the first write call.
   this.sync = true;
 
-  // a flag to know if we're processing previously buffered items, which
+  // A flag to know if we're processing previously buffered items, which
   // may call the _write() callback in the same tick, so that we don't
   // end up in an overlapped onwrite situation.
   this.bufferProcessing = false;
 
   // the callback that's passed to _write(chunk,cb)
   this.onwrite = onwrite.bind(undefined, stream);
 
-  // the callback that the user supplies to write(chunk,encoding,cb)
+  // The callback that the user supplies to write(chunk,encoding,cb)
   this.writecb = null;
 
   // the amount that is being written when _write is called.
@@ -139,7 +139,7 @@ function WritableState(options, stream, isDuplex) {
   // this must be 0 before 'finish' can be emitted
   this.pendingcb = 0;
 
-  // emit prefinish if the only thing we're waiting for is _write cbs
+  // Emit prefinish if the only thing we're waiting for is _write cbs
   // This is relevant for synchronous Transform streams
   this.prefinished = false;
 
@@ -376,7 +376,7 @@ function writeOrBuffer(stream, state, isBuf, chunk, encoding, cb) {
   state.length += len;
 
   var ret = state.length < state.highWaterMark;
-  // we must ensure that previous needDrain will not be reset to false.
+  // We must ensure that previous needDrain will not be reset to false.
   if (!ret)
     state.needDrain = true;