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

@@ -556,7 +556,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

@@ -68,7 +68,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

@@ -570,7 +570,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,