From b88477ef4dc82b2a77c90b5de65efab4cf507d3c Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Fri, 30 Mar 2018 13:38:45 +0300 Subject: 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 Reviewed-By: Shingo Inoue Reviewed-By: Richard Lau --- tools/doc/html.js | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) (limited to 'tools/doc/html.js') 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 = //; -// 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}