FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

tools: fix comment nits in tools/doc/*.js files · nodejs/node@140611b · GitHub

/ node Public

Commit 140611b

Browse files
vsemozhetbyt
authored and
targos
committed
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: #19696 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Shingo Inoue <leko.noor@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>
1 parent 01e3190 commit 140611b

6 files changed

Lines changed: 73 additions & 72 deletions

File tree

‎tools/doc/addon-verify.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ function once(fn) {
4747
}
4848

4949
function verifyFiles(files, blockName, onprogress, ondone) {
50-
// must have a .cc and a .js to be a valid test
50+
// Must have a .cc and a .js to be a valid test.
5151
if (!Object.keys(files).some((name) => /\.cc$/.test(name)) ||
5252
!Object.keys(files).some((name) => /\.js$/.test(name))) {
5353
return;
@@ -95,7 +95,7 @@ ${files[name].replace(
9595
});
9696

9797
fs.mkdir(dir, function() {
98-
// Ignore errors
98+
// Ignore errors.
9999

100100
const done = once(ondone);
101101
var waiting = files.length;

‎tools/doc/common.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ function extractAndParseYAML(text) {
1515
.replace(/^<!-- YAML/, '')
1616
.replace(/-->$/, '');
1717

18-
// js-yaml.safeLoad() throws on error
18+
// js-yaml.safeLoad() throws on error.
1919
const meta = yaml.safeLoad(text);
2020

2121
if (meta.added) {

‎tools/doc/generate.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@
2424
const processIncludes = require('./preprocess.js');
2525
const fs = require('fs');
2626

27-
// parse the args.
28-
// Don't use nopt or whatever for this. It's simple enough.
27+
// Parse the args.
28+
// Don't use nopt or whatever for this. It's simple enough.
2929

3030
const args = process.argv.slice(2);
3131
let format = 'json';
@@ -56,7 +56,7 @@ if (!filename) {
5656

5757
fs.readFile(filename, 'utf8', (er, input) => {
5858
if (er) throw er;
59-
// process the input for @include lines
59+
// Process the input for @include lines.
6060
processIncludes(filename, input, next);
6161
});
6262

‎tools/doc/html.js‎

Lines changed: 23 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ module.exports = toHTML;
3333
const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;
3434
const DOC_CREATED_REG_EXP = /<!--\s*introduced_in\s*=\s*v([0-9]+)\.([0-9]+)\.([0-9]+)\s*-->/;
3535

36-
// customized heading without id attribute
36+
// Customized heading without id attribute.
3737
const renderer = new marked.Renderer();
3838
renderer.heading = function(text, level) {
3939
return `<h${level}>${text}</h${level}>\n`;
@@ -42,7 +42,7 @@ marked.setOptions({
4242
renderer: renderer
4343
});
4444

45-
// TODO(chrisdickinson): never stop vomitting / fix this.
45+
// TODO(chrisdickinson): never stop vomiting / fix this.
4646
const gtocPath = path.resolve(path.join(
4747
__dirname,
4848
'..',
@@ -128,16 +128,16 @@ function render(opts, cb) {
128128
var { lexed, filename, template } = opts;
129129
const nodeVersion = opts.nodeVersion || process.version;
130130

131-
// get the section
131+
// Get the section.
132132
const section = getSection(lexed);
133133

134134
filename = path.basename(filename, '.md');
135135

136136
parseText(lexed);
137137
lexed = parseLists(lexed);
138138

139-
// generate the table of contents.
140-
// this mutates the lexed contents in-place.
139+
// Generate the table of contents.
140+
// This mutates the lexed contents in-place.
141141
buildToc(lexed, filename, function(er, toc) {
142142
if (er) return cb(er);
143143

@@ -162,8 +162,8 @@ function render(opts, cb) {
162162

163163
template = template.replace(/__ALTDOCS__/, altDocs(filename));
164164

165-
// content has to be the last thing we do with
166-
// the lexed tokens, because it's destructive.
165+
// Content has to be the last thing we do with the lexed tokens,
166+
// because it's destructive.
167167
const content = marked.parser(lexed);
168168
template = template.replace(/__CONTENT__/g, content);
169169

@@ -188,7 +188,7 @@ function analyticsScript(analytics) {
188188
`;
189189
}
190190

191-
// replace placeholders in text tokens
191+
// Replace placeholders in text tokens.
192192
function replaceInText(text) {
193193
return linkJsTypeDocs(linkManPages(text));
194194
}
@@ -244,8 +244,8 @@ function altDocs(filename) {
244244
`;
245245
}
246246

247-
// handle general body-text replacements
248-
// for example, link man page references to the actual page
247+
// Handle general body-text replacements.
248+
// For example, link man page references to the actual page.
249249
function parseText(lexed) {
250250
lexed.forEach(function(tok) {
251251
if (tok.type === 'table') {
@@ -272,8 +272,8 @@ function parseText(lexed) {
272272
});
273273
}
274274

275-
// just update the list item text in-place.
276-
// lists that come right after a heading are what we're after.
275+
// Just update the list item text in-place.
276+
// Lists that come right after a heading are what we're after.
277277
function parseLists(input) {
278278
var state = null;
279279
const savedState = [];
@@ -299,8 +299,8 @@ function parseLists(input) {
299299
const stabilityMatch = tok.text.match(STABILITY_TEXT_REG_EXP);
300300
const stability = Number(stabilityMatch[2]);
301301
const isStabilityIndex =
302-
index - 2 === headingIndex || // general
303-
index - 3 === headingIndex; // with api_metadata block
302+
index - 2 === headingIndex || // General.
303+
index - 3 === headingIndex; // With api_metadata block.
304304

305305
if (heading && isStabilityIndex) {
306306
heading.stability = stability;
@@ -408,17 +408,17 @@ function parseYAML(text) {
408408
return html.join('\n');
409409
}
410410

411-
// Syscalls which appear in the docs, but which only exist in BSD / OSX
411+
// Syscalls which appear in the docs, but which only exist in BSD / macOS.
412412
const BSD_ONLY_SYSCALLS = new Set(['lchmod']);
413413

414-
// Handle references to man pages, eg "open(2)" or "lchmod(2)"
415-
// Returns modified text, with such refs replace with HTML links, for example
416-
// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'
414+
// Handle references to man pages, eg "open(2)" or "lchmod(2)".
415+
// Returns modified text, with such refs replaced with HTML links, for example
416+
// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'.
417417
function linkManPages(text) {
418418
return text.replace(
419419
/(^|\s)([a-z.]+)\((\d)([a-z]?)\)/gm,
420420
(match, beginning, name, number, optionalCharacter) => {
421-
// name consists of lowercase letters, number is a single digit
421+
// Name consists of lowercase letters, number is a single digit.
422422
const displayAs = `${name}(${number}${optionalCharacter})`;
423423
if (BSD_ONLY_SYSCALLS.has(name)) {
424424
return `${beginning}<a href="https://www.freebsd.org/cgi/man.cgi?query=${name}` +
@@ -436,7 +436,7 @@ function linkJsTypeDocs(text) {
436436
var typeMatches;
437437

438438
// Handle types, for example the source Markdown might say
439-
// "This argument should be a {Number} or {String}"
439+
// "This argument should be a {Number} or {String}".
440440
for (i = 0; i < parts.length; i += 2) {
441441
typeMatches = parts[i].match(/\{([^}]+)\}/g);
442442
if (typeMatches) {
@@ -446,7 +446,7 @@ function linkJsTypeDocs(text) {
446446
}
447447
}
448448

449-
//XXX maybe put more stuff here?
449+
// TODO: maybe put more stuff here?
450450
return parts.join('`');
451451
}
452452

@@ -461,7 +461,7 @@ function parseAPIHeader(text) {
461461
return text;
462462
}
463463

464-
// section is just the first heading
464+
// Section is just the first heading.
465465
function getSection(lexed) {
466466
for (var i = 0, l = lexed.length; i < l; i++) {
467467
var tok = lexed[i];
@@ -533,7 +533,7 @@ const numberRe = /^(\d*)/;
533533
function versionSort(a, b) {
534534
a = a.trim();
535535
b = b.trim();
536-
let i = 0; // common prefix length
536+
let i = 0; // Common prefix length.
537537
while (i < a.length && i < b.length && a[i] === b[i]) i++;
538538
a = a.substr(i);
539539
b = b.substr(i);

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL