1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Vse Mozhet Byt 2018-03-30 13:38:45 +03:00
parent ae70e2bc34
commit b88477ef4d
6 changed files with 73 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
tools/doc/addon-verify.js
View File

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

2
tools/doc/common.js
View File

@ -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) {

6
tools/doc/generate.js
View File

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

46
tools/doc/html.js
View File

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

83
tools/doc/json.js
View File

@ -23,13 +23,13 @@
module.exports = doJSON;
// Take the lexed input, and return a JSON-encoded object
// A module looks like this: https://gist.github.com/1777387
// Take the lexed input, and return a JSON-encoded object.
// A module looks like this: https://gist.github.com/1777387.
const common = require('./common.js');
const marked = require('marked');
// 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`;
@ -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';

4
tools/doc/type-parser.js
View File

@ -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, '');