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>

1 files changed, 23 insertions, 23 deletions

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