tools: fix comment nits in tools/doc/*.js files

* Unify first letters case.
* Unify periods.
* Delete excess spaces.
* Add some blank lines as logical delimiters.
* Remove obvious comments.
* Combine short lines, rewrap lines more logically.
* Fix typos.
* "XXX" -> "TODO:", OSX -> macOS.

PR-URL: https://github.com/nodejs/node/pull/19696
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>

6 files changed, 73 insertions, 72 deletions

diff --git a/tools/doc/addon-verify.js b/tools/doc/addon-verify.js
index 2e72abb77f..9fcc71ed93 100644
--- a/tools/doc/addon-verify.js
+++ b/tools/doc/addon-verify.js
@@ -47,7 +47,7 @@ function once(fn) {
 }
 
 function verifyFiles(files, blockName, onprogress, ondone) {
-  // must have a .cc and a .js to be a valid test
+  // Must have a .cc and a .js to be a valid test.
   if (!Object.keys(files).some((name) => /\.cc$/.test(name)) ||
       !Object.keys(files).some((name) => /\.js$/.test(name))) {
     return;
@@ -95,7 +95,7 @@ ${files[name].replace(
   });
 
   fs.mkdir(dir, function() {
-    // Ignore errors
+    // Ignore errors.
 
     const done = once(ondone);
     var waiting = files.length;
diff --git a/tools/doc/common.js b/tools/doc/common.js
index 48ff3d1b82..553b52935f 100644
--- a/tools/doc/common.js
+++ b/tools/doc/common.js
@@ -15,7 +15,7 @@ function extractAndParseYAML(text) {
              .replace(/^<!-- YAML/, '')
              .replace(/-->$/, '');
 
-  // js-yaml.safeLoad() throws on error
+  // js-yaml.safeLoad() throws on error.
   const meta = yaml.safeLoad(text);
 
   if (meta.added) {
diff --git a/tools/doc/generate.js b/tools/doc/generate.js
index 1691db5ec0..0da9dba4e6 100644
--- a/tools/doc/generate.js
+++ b/tools/doc/generate.js
@@ -24,8 +24,8 @@
 const processIncludes = require('./preprocess.js');
 const fs = require('fs');
 
-// parse the args.
-// Don't use nopt or whatever for this.  It's simple enough.
+// Parse the args.
+// Don't use nopt or whatever for this. It's simple enough.
 
 const args = process.argv.slice(2);
 let format = 'json';
@@ -56,7 +56,7 @@ if (!filename) {
 
 fs.readFile(filename, 'utf8', (er, input) => {
   if (er) throw er;
-  // process the input for @include lines
+  // Process the input for @include lines.
   processIncludes(filename, input, next);
 });
 
diff --git a/tools/doc/html.js b/tools/doc/html.js
index f2e7ed396b..ff0230309e 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -33,7 +33,7 @@ module.exports = toHTML;
 const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;
 const DOC_CREATED_REG_EXP = /<!--\s*introduced_in\s*=\s*v([0-9]+)\.([0-9]+)\.([0-9]+)\s*-->/;
 
-// customized heading without id attribute
+// Customized heading without id attribute.
 const renderer = new marked.Renderer();
 renderer.heading = function(text, level) {
   return `<h${level}>${text}</h${level}>\n`;
@@ -42,7 +42,7 @@ marked.setOptions({
   renderer: renderer
 });
 
-// TODO(chrisdickinson): never stop vomitting / fix this.
+// TODO(chrisdickinson): never stop vomiting / fix this.
 const gtocPath = path.resolve(path.join(
   __dirname,
   '..',
@@ -128,7 +128,7 @@ function render(opts, cb) {
   var { lexed, filename, template } = opts;
   const nodeVersion = opts.nodeVersion || process.version;
 
-  // get the section
+  // Get the section.
   const section = getSection(lexed);
 
   filename = path.basename(filename, '.md');
@@ -136,8 +136,8 @@ function render(opts, cb) {
   parseText(lexed);
   lexed = parseLists(lexed);
 
-  // generate the table of contents.
-  // this mutates the lexed contents in-place.
+  // Generate the table of contents.
+  // This mutates the lexed contents in-place.
   buildToc(lexed, filename, function(er, toc) {
     if (er) return cb(er);
 
@@ -162,8 +162,8 @@ function render(opts, cb) {
 
     template = template.replace(/__ALTDOCS__/, altDocs(filename));
 
-    // content has to be the last thing we do with
-    // the lexed tokens, because it's destructive.
+    // Content has to be the last thing we do with the lexed tokens,
+    // because it's destructive.
     const content = marked.parser(lexed);
     template = template.replace(/__CONTENT__/g, content);
 
@@ -188,7 +188,7 @@ function analyticsScript(analytics) {
   `;
 }
 
-// replace placeholders in text tokens
+// Replace placeholders in text tokens.
 function replaceInText(text) {
   return linkJsTypeDocs(linkManPages(text));
 }
@@ -244,8 +244,8 @@ function altDocs(filename) {
   `;
 }
 
-// handle general body-text replacements
-// for example, link man page references to the actual page
+// Handle general body-text replacements.
+// For example, link man page references to the actual page.
 function parseText(lexed) {
   lexed.forEach(function(tok) {
     if (tok.type === 'table') {
@@ -272,8 +272,8 @@ function parseText(lexed) {
   });
 }
 
-// just update the list item text in-place.
-// lists that come right after a heading are what we're after.
+// Just update the list item text in-place.
+// Lists that come right after a heading are what we're after.
 function parseLists(input) {
   var state = null;
   const savedState = [];
@@ -299,8 +299,8 @@ function parseLists(input) {
         const stabilityMatch = tok.text.match(STABILITY_TEXT_REG_EXP);
         const stability = Number(stabilityMatch[2]);
         const isStabilityIndex =
-          index - 2 === headingIndex || // general
-          index - 3 === headingIndex;   // with api_metadata block
+          index - 2 === headingIndex || // General.
+          index - 3 === headingIndex;   // With api_metadata block.
 
         if (heading && isStabilityIndex) {
           heading.stability = stability;
@@ -408,17 +408,17 @@ function parseYAML(text) {
   return html.join('\n');
 }
 
-// Syscalls which appear in the docs, but which only exist in BSD / OSX
+// Syscalls which appear in the docs, but which only exist in BSD / macOS.
 const BSD_ONLY_SYSCALLS = new Set(['lchmod']);
 
-// Handle references to man pages, eg "open(2)" or "lchmod(2)"
-// Returns modified text, with such refs replace with HTML links, for example
-// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'
+// Handle references to man pages, eg "open(2)" or "lchmod(2)".
+// Returns modified text, with such refs replaced with HTML links, for example
+// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'.
 function linkManPages(text) {
   return text.replace(
     /(^|\s)([a-z.]+)\((\d)([a-z]?)\)/gm,
     (match, beginning, name, number, optionalCharacter) => {
-      // name consists of lowercase letters, number is a single digit
+      // Name consists of lowercase letters, number is a single digit.
       const displayAs = `${name}(${number}${optionalCharacter})`;
       if (BSD_ONLY_SYSCALLS.has(name)) {
         return `${beginning}<a href="https://www.freebsd.org/cgi/man.cgi?query=${name}` +
@@ -436,7 +436,7 @@ function linkJsTypeDocs(text) {
   var typeMatches;
 
   // Handle types, for example the source Markdown might say
-  // "This argument should be a {Number} or {String}"
+  // "This argument should be a {Number} or {String}".
   for (i = 0; i < parts.length; i += 2) {
     typeMatches = parts[i].match(/\{([^}]+)\}/g);
     if (typeMatches) {
@@ -446,7 +446,7 @@ function linkJsTypeDocs(text) {
     }
   }
 
-  //XXX maybe put more stuff here?
+  // TODO: maybe put more stuff here?
   return parts.join('`');
 }
 
@@ -461,7 +461,7 @@ function parseAPIHeader(text) {
   return text;
 }
 
-// section is just the first heading
+// Section is just the first heading.
 function getSection(lexed) {
   for (var i = 0, l = lexed.length; i < l; i++) {
     var tok = lexed[i];
@@ -533,7 +533,7 @@ const numberRe = /^(\d*)/;
 function versionSort(a, b) {
   a = a.trim();
   b = b.trim();
-  let i = 0;  // common prefix length
+  let i = 0; // Common prefix length.
   while (i < a.length && i < b.length && a[i] === b[i]) i++;
   a = a.substr(i);
   b = b.substr(i);
diff --git a/tools/doc/json.js b/tools/doc/json.js
index 2966e4c3d9..6eaee8c7fc 100644
--- a/tools/doc/json.js
+++ b/tools/doc/json.js
@@ -23,13 +23,13 @@
 
 module.exports = doJSON;
 
-// Take the lexed input, and return a JSON-encoded object
-// A module looks like this: https://gist.github.com/1777387
+// Take the lexed input, and return a JSON-encoded object.
+// A module looks like this: https://gist.github.com/1777387.
 
 const common = require('./common.js');
 const marked = require('marked');
 
-// customized heading without id attribute
+// Customized heading without id attribute.
 const renderer = new marked.Renderer();
 renderer.heading = function(text, level) {
   return `<h${level}>${text}</h${level}>\n`;
@@ -68,20 +68,19 @@ function doJSON(input, filename, cb) {
                             JSON.stringify(tok)));
       }
 
-      // Sometimes we have two headings with a single
-      // blob of description.  Treat as a clone.
+      // Sometimes we have two headings with a single blob of description.
+      // Treat as a clone.
       if (current &&
           state === 'AFTERHEADING' &&
           depth === tok.depth) {
         var clone = current;
         current = newSection(tok);
         current.clone = clone;
-        // don't keep it around on the stack.
+        // Don't keep it around on the stack.
         stack.pop();
       } else {
-        // if the level is greater than the current depth,
-        // then it's a child, so we should just leave the stack
-        // as it is.
+        // If the level is greater than the current depth,
+        // then it's a child, so we should just leave the stack as it is.
         // However, if it's a sibling or higher, then it implies
         // the closure of the other sections that came before.
         // root is always considered the level=0 section,
@@ -99,19 +98,19 @@ function doJSON(input, filename, cb) {
       stack.push(current);
       state = 'AFTERHEADING';
       return;
-    } // heading
+    }
 
-    // Immediately after a heading, we can expect the following
+    // Immediately after a heading, we can expect the following:
     //
-    // { type: 'blockquote_start' }
+    // { type: 'blockquote_start' },
     // { type: 'paragraph', text: 'Stability: ...' },
-    // { type: 'blockquote_end' }
+    // { type: 'blockquote_end' },
     //
-    // a list: starting with list_start, ending with list_end,
+    // A list: starting with list_start, ending with list_end,
     // maybe containing other nested lists in each item.
     //
-    // If one of these isn't found, then anything that comes between
-    // here and the next heading should be parsed as the desc.
+    // If one of these isn't found, then anything that comes
+    // between here and the next heading should be parsed as the desc.
     var stability;
     if (state === 'AFTERHEADING') {
       if (type === 'blockquote_start') {
@@ -171,7 +170,7 @@ function doJSON(input, filename, cb) {
 
   });
 
-  // finish any sections left open
+  // Finish any sections left open.
   while (root !== (current = stack.pop())) {
     finishSection(current, stack[stack.length - 1]);
   }
@@ -180,14 +179,15 @@ function doJSON(input, filename, cb) {
 }
 
 
-// go from something like this:
+// Go from something like this:
+//
 // [ { type: 'list_item_start' },
 //   { type: 'text',
 //     text: '`settings` Object, Optional' },
 //   { type: 'list_start', ordered: false },
 //   { type: 'list_item_start' },
 //   { type: 'text',
-//     text: 'exec: String, file path to worker file.  Default: `__filename`' },
+//     text: 'exec: String, file path to worker file. Default: `__filename`' },
 //   { type: 'list_item_end' },
 //   { type: 'list_item_start' },
 //   { type: 'text',
@@ -204,7 +204,9 @@ function doJSON(input, filename, cb) {
 //   { type: 'list_end' },
 //   { type: 'list_item_end' },
 //   { type: 'list_end' } ]
+//
 // to something like:
+//
 // [ { name: 'settings',
 //     type: 'object',
 //     optional: true,
@@ -228,7 +230,7 @@ function processList(section) {
   var current;
   const stack = [];
 
-  // for now, *just* build the heirarchical list
+  // For now, *just* build the hierarchical list.
   list.forEach(function(tok) {
     const type = tok.type;
     if (type === 'space') return;
@@ -260,23 +262,23 @@ function processList(section) {
     }
   });
 
-  // shove the name in there for properties, since they are always
-  // just going to be the value etc.
+  // Shove the name in there for properties,
+  // since they are always just going to be the value etc.
   if (section.type === 'property' && values[0]) {
     values[0].textRaw = `\`${section.name}\` ${values[0].textRaw}`;
   }
 
-  // now pull the actual values out of the text bits.
+  // Now pull the actual values out of the text bits.
   values.forEach(parseListItem);
 
   // Now figure out what this list actually means.
-  // depending on the section type, the list could be different things.
+  // Depending on the section type, the list could be different things.
 
   switch (section.type) {
     case 'ctor':
     case 'classMethod':
     case 'method':
-      // each item is an argument, unless the name is 'return',
+      // Each item is an argument, unless the name is 'return',
       // in which case it's the return value.
       section.signatures = section.signatures || [];
       var sig = {};
@@ -292,8 +294,8 @@ function processList(section) {
       break;
 
     case 'property':
-      // there should be only one item, which is the value.
-      // copy the data up to the section.
+      // There should be only one item, which is the value.
+      // Copy the data up to the section.
       var value = values[0] || {};
       delete value.name;
       section.typeof = value.type || section.typeof;
@@ -304,7 +306,7 @@ function processList(section) {
       break;
 
     case 'event':
-      // event: each item is an argument.
+      // Event: each item is an argument.
       section.params = values;
       break;
 
@@ -336,7 +338,7 @@ function parseSignature(text, sig) {
     var optional = false;
     var def;
 
-    // for grouped optional params such as someMethod(a[, b[, c]])
+    // For grouped optional params such as someMethod(a[, b[, c]]).
     var pos;
     for (pos = 0; pos < p.length; pos++) {
       if (optionalCharDict[p[pos]] === undefined) { break; }
@@ -358,7 +360,7 @@ function parseSignature(text, sig) {
     if (!param) {
       param = sig.params[i] = { name: p };
     }
-    // at this point, the name should match.
+    // At this point, the name should match.
     if (p !== param.name) {
       console.error('Warning: invalid param "%s"', p);
       console.error(` > ${JSON.stringify(param)}`);
@@ -374,8 +376,8 @@ function parseListItem(item) {
   if (item.options) item.options.forEach(parseListItem);
   if (!item.textRaw) return;
 
-  // the goal here is to find the name, type, default, and optional.
-  // anything left over is 'desc'
+  // The goal here is to find the name, type, default, and optional.
+  // Anything left over is 'desc'.
   var text = item.textRaw.trim();
   // text = text.replace(/^(Argument|Param)s?\s*:?\s*/i, '');
 
@@ -449,9 +451,8 @@ function finishSection(section, parent) {
   if (!section.list) section.list = [];
   processList(section);
 
-  // classes sometimes have various 'ctor' children
-  // which are actually just descriptions of a constructor
-  // class signature.
+  // Classes sometimes have various 'ctor' children
+  // which are actually just descriptions of a constructor class signature.
   // Merge them into the parent.
   if (section.type === 'class' && section.ctors) {
     section.signatures = section.signatures || [];
@@ -466,8 +467,8 @@ function finishSection(section, parent) {
     delete section.ctors;
   }
 
-  // properties are a bit special.
-  // their "type" is the type of object, not "property"
+  // Properties are a bit special.
+  // Their "type" is the type of object, not "property".
   if (section.properties) {
     section.properties.forEach(function(p) {
       if (p.typeof) p.type = p.typeof;
@@ -476,7 +477,7 @@ function finishSection(section, parent) {
     });
   }
 
-  // handle clones
+  // Handle clones.
   if (section.clone) {
     var clone = section.clone;
     delete section.clone;
@@ -494,7 +495,7 @@ function finishSection(section, parent) {
     plur = `${section.type}s`;
   }
 
-  // if the parent's type is 'misc', then it's just a random
+  // If the parent's type is 'misc', then it's just a random
   // collection of stuff, like the "globals" section.
   // Make the children top-level items.
   if (section.type === 'misc') {
@@ -554,7 +555,7 @@ function deepCopy_(src) {
 }
 
 
-// these parse out the contents of an H# tag
+// These parse out the contents of an H# tag.
 const eventExpr = /^Event(?::|\s)+['"]?([^"']+).*$/i;
 const classExpr = /^Class:\s*([^ ]+).*$/i;
 const propExpr = /^[^.]+\.([^ .()]+)\s*$/;
@@ -566,7 +567,7 @@ var paramExpr = /\((.*)\);?$/;
 
 function newSection(tok) {
   const section = {};
-  // infer the type from the text.
+  // Infer the type from the text.
   const text = section.textRaw = tok.text;
   if (text.match(eventExpr)) {
     section.type = 'event';
diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js
index dbf1538c10..1cbd1a5552 100644
--- a/tools/doc/type-parser.js
+++ b/tools/doc/type-parser.js
@@ -5,7 +5,7 @@ const jsDocPrefix = 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/';
 const jsPrimitiveUrl = `${jsDocPrefix}Data_structures`;
 const jsPrimitives = {
   'boolean': 'Boolean',
-  'integer': 'Number', // not a primitive, used for clarification
+  'integer': 'Number', // Not a primitive, used for clarification.
   'null': 'Null',
   'number': 'Number',
   'string': 'String',
@@ -110,7 +110,7 @@ function toLink(typeInput) {
       let typeUrl = null;
 
       // To support type[], type[][] etc., we store the full string
-      // and use the bracket-less version to lookup the type URL
+      // and use the bracket-less version to lookup the type URL.
       const typeTextFull = typeText;
       typeText = typeText.replace(arrayPart, '');