Skip to content

Commit

Permalink
tools: fix comment nits in tools/doc/*.js files
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
vsemozhetbyt authored and MylesBorins committed Aug 17, 2018
1 parent eb5f085 commit 59b99e8
Show file tree
Hide file tree
Showing 6 changed files with 73 additions and 72 deletions.
4 changes: 2 additions & 2 deletions tools/doc/addon-verify.js
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -95,7 +95,7 @@ ${files[name].replace(
});

fs.mkdir(dir, function() {
// Ignore errors
// Ignore errors.

const done = once(ondone);
var waiting = files.length;
Expand Down
2 changes: 1 addition & 1 deletion tools/doc/common.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
6 changes: 3 additions & 3 deletions tools/doc/generate.js
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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);
});

Expand Down
46 changes: 23 additions & 23 deletions tools/doc/html.js
Original file line number Diff line number Diff line change
Expand Up @@ -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`;
Expand All @@ -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,
'..',
Expand Down Expand Up @@ -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);

Expand All @@ -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);

Expand All @@ -188,7 +188,7 @@ function analyticsScript(analytics) {
`;
}

// replace placeholders in text tokens
// Replace placeholders in text tokens.
function replaceInText(text) {
return linkJsTypeDocs(linkManPages(text));
}
Expand Down Expand Up @@ -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') {
Expand All @@ -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 = [];
Expand All @@ -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;
Expand Down Expand Up @@ -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}` +
Expand All @@ -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) {
Expand All @@ -446,7 +446,7 @@ function linkJsTypeDocs(text) {
}
}

//XXX maybe put more stuff here?
// TODO: maybe put more stuff here?
return parts.join('`');
}

Expand All @@ -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];
Expand Down Expand Up @@ -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);
Expand Down
Loading

0 comments on commit 59b99e8

Please sign in to comment.