diff --git a/tools/doc/addon-verify.js b/tools/doc/addon-verify.js index 2e72abb77f925f..9fcc71ed93f0c9 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 48ff3d1b828d14..553b52935fd709 100644 --- a/tools/doc/common.js +++ b/tools/doc/common.js @@ -15,7 +15,7 @@ function extractAndParseYAML(text) { .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 1691db5ec0046b..0da9dba4e6558f 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 f2e7ed396b7cc4..ff0230309ee99a 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 = //; -// customized heading without id attribute +// Customized heading without id attribute. const renderer = new marked.Renderer(); renderer.heading = function(text, level) { return `${text}\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 -// 'open(2)' +// Handle references to man pages, eg "open(2)" or "lchmod(2)". +// Returns modified text, with such refs replaced with HTML links, for example +// 'open(2)'. 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}${text}\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 dbf1538c10f64b..1cbd1a5552b00d 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, '');