Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

tools: fix comment nits in tools/doc/*.js files #19696

Closed
wants to merge 3 commits into from
Closed

tools: fix comment nits in tools/doc/*.js files #19696

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5d21a89
tools: Fix comment nits in tools/doc/*.js files
vsemozhetbyt Mar 30, 2018
21591d3
fixup: "XXX" -> "TODO:"
vsemozhetbyt Mar 30, 2018
b588bb9
fixup: OSX -> macOS
vsemozhetbyt Mar 30, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions tools/doc/addon-verify.js
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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 / OSX.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

macOS since we're changing this line?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

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?
// XXX Maybe put more stuff here?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: being on it, you might also change XXX to TODO.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

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