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: #19696
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>

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;

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) {

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);
 });
 

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,16 +128,16 @@ 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');
 
   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);