doc,lib,test: capitalize comment sentences

This activates the eslint capitalize comment rule for comments
above 50 characters.

PR-URL: #24996
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

.eslintrc.js

@@ -60,9 +60,9 @@ module.exports = {
     'brace-style': ['error', '1tbs', { allowSingleLine: true }],
     'capitalized-comments': ['error', 'always', {
       line: {
-        // Ignore all lines that have less characters than 62 and all lines that
+        // Ignore all lines that have less characters than 50 and all lines that
         // start with something that looks like a variable name or code.
-        ignorePattern: '^.{0,62}$|^ [a-z]+ ?[0-9A-Z_.(/=:-]',
+        ignorePattern: '^.{0,50}$|^ [a-z]+ ?[0-9A-Z_.(/=:[#-]',
         ignoreInlineComments: true,
         ignoreConsecutiveComments: true
       },

benchmark/_benchmark_progress.js

@@ -40,7 +40,7 @@ class BenchmarkProgress {
     this.completedConfig = 0;
     // Total number of configurations for the current file
     this.scheduledConfig = 0;
-    this.interval = 0;  // result of setInterval for updating the elapsed time
+    this.interval;  // Updates the elapsed time.
   }
 
   startQueue(index) {

benchmark/napi/function_args/index.js

@@ -1,4 +1,4 @@
-// show the difference between calling a V8 binding C++ function
+// Show the difference between calling a V8 binding C++ function
 // relative to a comparable N-API C++ function,
 // in various types/numbers of arguments.
 // Reports n of calls per second.

benchmark/napi/function_call/index.js

@@ -1,4 +1,4 @@
-// show the difference between calling a short js function
+// Show the difference between calling a short js function
 // relative to a comparable C++ function.
 // Reports n of calls per second.
 // Note that JS speed goes up, while cxx speed stays about the same.

benchmark/net/net-pipe.js

@@ -48,7 +48,7 @@ function main({ dur, len, type }) {
       socket.pipe(writer);
 
       setTimeout(function() {
-        // multiply by 2 since we're sending it first one way
+        // Multiply by 2 since we're sending it first one way
         // then then back again.
         const bytes = writer.received * 2;
         const gbits = (bytes * 8) / (1024 * 1024 * 1024);

benchmark/net/tcp-raw-c2s.js

@@ -47,12 +47,12 @@ function main({ dur, len, type }) {
     }, dur * 1000);
 
     clientHandle.onread = function(buffer) {
-      // we're not expecting to ever get an EOF from the client.
-      // just lots of data forever.
+      // We're not expecting to ever get an EOF from the client.
+      // Just lots of data forever.
       if (!buffer)
         fail('read');
 
-      // don't slice the buffer.  the point of this is to isolate, not
+      // Don't slice the buffer. The point of this is to isolate, not
       // simulate real traffic.
       bytes += buffer.byteLength;
     };

benchmark/net/tcp-raw-pipe.js

@@ -44,8 +44,8 @@ function main({ dur, len, type }) {
       fail(err, 'connect');
 
     clientHandle.onread = function(buffer) {
-      // we're not expecting to ever get an EOF from the client.
-      // just lots of data forever.
+      // We're not expecting to ever get an EOF from the client.
+      // Just lots of data forever.
       if (!buffer)
         fail('read');
 
@@ -105,7 +105,7 @@ function main({ dur, len, type }) {
     clientHandle.readStart();
 
     setTimeout(function() {
-      // multiply by 2 since we're sending it first one way
+      // Multiply by 2 since we're sending it first one way
       // then then back again.
       bench.end(2 * (bytes * 8) / (1024 * 1024 * 1024));
       process.exit(0);

benchmark/net/tcp-raw-s2c.js

@@ -110,12 +110,12 @@ function main({ dur, len, type }) {
     connectReq.oncomplete = function() {
       var bytes = 0;
       clientHandle.onread = function(buffer) {
-        // we're not expecting to ever get an EOF from the client.
-        // just lots of data forever.
+        // We're not expecting to ever get an EOF from the client.
+        // Just lots of data forever.
         if (!buffer)
           fail('read');
 
-        // don't slice the buffer.  the point of this is to isolate, not
+        // Don't slice the buffer. The point of this is to isolate, not
         // simulate real traffic.
         bytes += buffer.byteLength;
       };

benchmark/tls/tls-connect.js

@@ -59,7 +59,7 @@ function makeConnection() {
 
 function done() {
   running = false;
-  // it's only an established connection if they both saw it.
+  // It's only an established connection if they both saw it.
   // because we destroy the server somewhat abruptly, these
   // don't always match.  Generally, serverConn will be
   // the smaller number, but take the min just to be sure.

doc/api/async_hooks.md

@@ -69,7 +69,7 @@ function before(asyncId) { }
 // After is called just after the resource's callback has finished.
 function after(asyncId) { }
 
-// destroy is called when an AsyncWrap instance is destroyed.
+// Destroy is called when an AsyncWrap instance is destroyed.
 function destroy(asyncId) { }
 
 // promiseResolve is called only for promise resources, when the

doc/api/cluster.md

@@ -322,7 +322,7 @@ if (cluster.isMaster) {
 
   process.on('message', (msg) => {
     if (msg === 'shutdown') {
-      // initiate graceful close of any connections to server
+      // Initiate graceful close of any connections to server
     }
   });
 }

doc/api/domain.md

@@ -248,7 +248,7 @@ const serverDomain = domain.create();
 serverDomain.run(() => {
   // server is created in the scope of serverDomain
   http.createServer((req, res) => {
-    // req and res are also created in the scope of serverDomain
+    // Req and res are also created in the scope of serverDomain
     // however, we'd prefer to have a separate domain for each request.
     // create it first thing, and add req and res to it.
     const reqd = domain.create();
@@ -316,7 +316,7 @@ const d = domain.create();
 
 function readSomeFile(filename, cb) {
   fs.readFile(filename, 'utf8', d.bind((er, data) => {
-    // if this throws, it will also be passed to the domain
+    // If this throws, it will also be passed to the domain
     return cb(er, data ? JSON.parse(data) : null);
   }));
 }

doc/api/esm.md

@@ -242,7 +242,7 @@ export async function dynamicInstantiate(url) {
   return {
     exports: ['customExportName'],
     execute: (exports) => {
-      // get and set functions provided for pre-allocated export names
+      // Get and set functions provided for pre-allocated export names
       exports.customExportName.set('value');
     }
   };

doc/api/events.md

@@ -641,7 +641,7 @@ const logFnWrapper = listeners[0];
 // 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
+// Logs "log once" to the console and removes the listener
 logFnWrapper();
 
 emitter.on('log', () => console.log('log persistently'));

doc/api/path.md

@@ -299,7 +299,7 @@ path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
 // Returns: '/foo/bar/baz/asdf'
 
 path.join('foo', {}, 'bar');
-// throws 'TypeError: Path must be a string. Received {}'
+// Throws 'TypeError: Path must be a string. Received {}'
 ```
 
 A [`TypeError`][] is thrown if any of the path segments is not a string.
@@ -495,7 +495,7 @@ path.resolve('/foo/bar', '/tmp/file/');
 // Returns: '/tmp/file'
 
 path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
-// if the current working directory is /home/myself/node,
+// If the current working directory is /home/myself/node,
 // this returns '/home/myself/node/wwwroot/static_files/gif/image.gif'
 ```
 

doc/api/perf_hooks.md

@@ -331,7 +331,7 @@ const {
 } = require('perf_hooks');
 
 const obs = new PerformanceObserver((list, observer) => {
-  // called three times synchronously. list contains one item
+  // Called three times synchronously. list contains one item
 });
 obs.observe({ entryTypes: ['mark'] });
 

doc/api/stream.md

@@ -118,8 +118,8 @@ that implements an HTTP server:
 const http = require('http');
 
 const server = http.createServer((req, res) => {
-  // req is an http.IncomingMessage, which is a Readable Stream
-  // res is an http.ServerResponse, which is a Writable Stream
+  // `req` is an http.IncomingMessage, which is a Readable Stream
+  // `res` is an http.ServerResponse, which is a Writable Stream
 
   let body = '';
   // Get the data as utf8 strings.
@@ -1195,7 +1195,7 @@ function parseHeader(stream, callback) {
         stream.removeListener('readable', onReadable);
         if (buf.length)
           stream.unshift(buf);
-        // now the body of the message can be read from the stream.
+        // Now the body of the message can be read from the stream.
         callback(null, header, stream);
       } else {
         // still reading the header.
@@ -1930,19 +1930,19 @@ pause/resume mechanism, and a data callback, the low-level source can be wrapped
 by the custom `Readable` instance:
 
 ```js
-// source is an object with readStop() and readStart() methods,
+// `_source` is an object with readStop() and readStart() methods,
 // and an `ondata` member that gets called when it has data, and
 // an `onend` member that gets called when the data is over.
 
 class SourceWrapper extends Readable {
   constructor(options) {
     super(options);
 
-    this._source = getLowlevelSourceObject();
+    this._source = getLowLevelSourceObject();
 
     // Every time there's data, push it into the internal buffer.
     this._source.ondata = (chunk) => {
-      // if push() returns false, then stop reading from source
+      // If push() returns false, then stop reading from source
       if (!this.push(chunk))
         this._source.readStop();
     };
@@ -2391,7 +2391,7 @@ For example, consider the following code:
 // WARNING!  BROKEN!
 net.createServer((socket) => {
 
-  // we add an 'end' listener, but never consume the data
+  // We add an 'end' listener, but never consume the data
   socket.on('end', () => {
     // It will never get here.
     socket.end('The message was received but was not processed.\n');

doc/api/tracing.md

@@ -133,7 +133,7 @@ t2.enable();
 // Prints 'node,node.perf,v8'
 console.log(trace_events.getEnabledCategories());
 
-t2.disable(); // will only disable emission of the 'node.perf' category
+t2.disable(); // Will only disable emission of the 'node.perf' category
 
 // Prints 'node,v8'
 console.log(trace_events.getEnabledCategories());

doc/api/vm.md

@@ -33,7 +33,7 @@ const sandbox = { x: 2 };
 vm.createContext(sandbox); // Contextify the sandbox.
 
 const code = 'x += 40; var y = 17;';
-// x and y are global variables in the sandboxed environment.
+// `x` and `y` are global variables in the sandboxed environment.
 // Initially, x has the value 2 because that is the value of sandbox.x.
 vm.runInContext(code, sandbox);
 

doc/api/zlib.md

@@ -81,7 +81,7 @@ request.on('response', (response) => {
   const output = fs.createWriteStream('example.com_index.html');
 
   switch (response.headers['content-encoding']) {
-    // or, just use zlib.createUnzip() to handle both cases
+    // Or, just use zlib.createUnzip() to handle both cases
     case 'gzip':
       response.pipe(zlib.createGunzip()).pipe(output);
       break;

doc/guides/writing-and-running-benchmarks.md

@@ -397,7 +397,7 @@ const options = {
   flags: ['--zero-fill-buffers']
 };
 
-// main and configs are required, options is optional.
+// `main` and `configs` are required, `options` is optional.
 const bench = common.createBenchmark(main, configs, options);
 
 // Note that any code outside main will be run twice,

lib/_http_client.js

@@ -555,7 +555,7 @@ function parserOnIncomingClient(res, shouldKeepAlive) {
   req.res = res;
   res.req = req;
 
-  // add our listener first, so that we guarantee socket cleanup
+  // Add our listener first, so that we guarantee socket cleanup
   res.on('end', responseOnEnd);
   req.on('prefinish', requestOnPrefinish);
   var handled = req.emit('response', res);

lib/_http_common.js

@@ -116,11 +116,11 @@ function parserOnHeadersComplete(versionMajor, versionMinor, headers, method,
 function parserOnBody(b, start, len) {
   const stream = this.incoming;
 
-  // if the stream has already been removed, then drop it.
+  // If the stream has already been removed, then drop it.
   if (stream === null)
     return;
 
-  // pretend this was the result of a stream._read call.
+  // Pretend this was the result of a stream._read call.
   if (len > 0 && !stream._dumped) {
     var slice = b.slice(start, start + len);
     var ret = stream.push(slice);

lib/_http_incoming.js

@@ -67,7 +67,7 @@ function IncomingMessage(socket) {
   this.client = socket;
 
   this._consuming = false;
-  // flag for when we decide that this message cannot possibly be
+  // Flag for when we decide that this message cannot possibly be
   // read by the user, so there's no point continuing to handle it.
   this._dumped = false;
 }

lib/_http_server.js

@@ -574,7 +574,7 @@ function resOnFinish(req, res, socket, state, server) {
 
   state.incoming.shift();
 
-  // if the user never called req.read(), and didn't pipe() or
+  // If the user never called req.read(), and didn't pipe() or
   // .resume() or .on('data'), then we call req._dump() so that the
   // bytes will be pulled off the wire.
   if (!req._consuming && !req._readableState.resumeScheduled)

lib/_stream_duplex.js

@@ -67,7 +67,7 @@ function Duplex(options) {
 }
 
 Object.defineProperty(Duplex.prototype, 'writableHighWaterMark', {
-  // making it explicit this property is not enumerable
+  // Making it explicit this property is not enumerable
   // because otherwise some prototype manipulation in
   // userland will fail
   enumerable: false,
@@ -77,7 +77,7 @@ Object.defineProperty(Duplex.prototype, 'writableHighWaterMark', {
 });
 
 Object.defineProperty(Duplex.prototype, 'writableBuffer', {
-  // making it explicit this property is not enumerable
+  // Making it explicit this property is not enumerable
   // because otherwise some prototype manipulation in
   // userland will fail
   enumerable: false,
@@ -87,7 +87,7 @@ Object.defineProperty(Duplex.prototype, 'writableBuffer', {
 });
 
 Object.defineProperty(Duplex.prototype, 'writableLength', {
-  // making it explicit this property is not enumerable
+  // Making it explicit this property is not enumerable
   // because otherwise some prototype manipulation in
   // userland will fail
   enumerable: false,
@@ -112,7 +112,7 @@ function onEndNT(self) {
 }
 
 Object.defineProperty(Duplex.prototype, 'destroyed', {
-  // making it explicit this property is not enumerable
+  // Making it explicit this property is not enumerable
   // because otherwise some prototype manipulation in
   // userland will fail
   enumerable: false,