github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

[doclint] remove preprocessor's gen:copy and gen:paste commands

Browse Source 
These commands proved to be over-complicating the documentation source.
We should keep documentation source as simple to edit as possible to
make it friendly to contributions.

This patch keeps the gen:version command as it is non-invasive.
This commit is contained in:
Andrey Lushnikov
2017-07-31 21:14:50 -07:00
parent 2acfec0989
commit 337315c5fe
3 changed files with 8 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
utils/doclint/preprocessor/index.js
View File

@@ -45,27 +45,13 @@ module.exports = function(sources) {
commands = validateCommands(commands, messages);
// Extract copied text.
let copyIds = new Map();
for (let command of commands) {
if (command.name !== 'copy')
continue;
const copyText = command.source.text().substring(command.from, command.to);
copyIds.set(command.arg, copyText);
}
let changedSources = new Set();
// Iterate commands in reverse order so that edits don't conflict.
commands.sort((a, b) => b.from - a.from);
for (let command of commands) {
let newText = command.source.text();
if (command.name === 'version') {
if (command.name === 'version')
newText = replaceInText(newText, command.from, command.to, PUPPETEER_VERSION);
} else if (command.name === 'paste') {
let copyText = copyIds.get(command.arg);
copyText = `\n<!-- Text below is automatically copied from "gen:copy(${command.arg})" -->` + copyText;
newText = replaceInText(newText, command.from, command.to, copyText);
}
if (command.source.setText(newText))
changedSources.add(command.source);
}
@@ -84,42 +70,9 @@ function validateCommands(commands, outMessages) {
let goodCommands = commands.filter(command => {
if (command.name === 'version')
return check(command, !command.arg, `"gen:version" should not have argument`);
if (command.name === 'copy')
return check(command, command.arg, `"gen:copy" should have argument - copyId`);
if (command.name === 'paste')
return check(command, command.arg, `"gen:paste" should have argument - name of the register to paste from`);
check(command, false, `Unknown command: "gen:${command.name}"`);
});
// Make sure copy commands don't clash ids.
let copyIds = new Map();
goodCommands = goodCommands.filter(command => {
if (command.name !== 'copy')
return true;
const duplicateCopy = copyIds.get(command.arg);
const duplicatePath = duplicateCopy ? duplicateCopy.source.projectPath() : '';
if (check(command, !duplicateCopy, `"gen:copy" tries to re-define copy id "${command.arg}" - previously defined in ${duplicatePath}`)) {
copyIds.set(command.arg, command);
return true;
}
return false;
});
// Make sure paste commands refer to proper ids, and every copyId is used at least
// once.
let unusedCopyIds = new Set(copyIds.keys());
goodCommands = goodCommands.filter(command => {
if (command.name !== 'paste')
return true;
unusedCopyIds.delete(command.arg);
if (check(command, copyIds.has(command.arg), `"gen:paste" refers to unknown copy id "${command.arg}"`))
return true;
return false;
});
for (let copyId of unusedCopyIds) {
let command = copyIds.get(copyId);
check(command, false, `"gen:copy" defines unused copy id "${copyId}"`);
}
return goodCommands;
function check(command, condition, message) {
@@ -130,6 +83,13 @@ function validateCommands(commands, outMessages) {
}
}
/**
* @param {string} text
* @param {number} from
* @param {number} to
* @param {string} newText
* @return {string}
*/
function replaceInText(text, from, to, newText) {
return text.substring(0, from) + newText + text.substring(to);
}

62
utils/doclint/preprocessor/test.js
View File

@@ -19,16 +19,6 @@ const SourceFactory = require('../SourceFactory');
const factory = new SourceFactory();
const VERSION = require('../../../package.json').version;
let COPY_INPUT = `
<!-- gen:copy("test") -->Heyo!<!-- gen:stop -->
<!-- gen:paste("test") --><!-- gen:stop -->
`;
let COPY_EXPECTED = `
<!-- gen:copy("test") -->Heyo!<!-- gen:stop -->
<!-- gen:paste("test") -->
<!-- Text below is automatically copied from "gen:copy("test")" -->Heyo!<!-- gen:stop -->
`;
describe('preprocessor', function() {
it('should throw for unknown command', function() {
let source = factory.createForTest('doc.md', getCommand('unknownCommand()'));
@@ -62,58 +52,6 @@ describe('preprocessor', function() {
expect(messages[0].text).toContain(`Failed to find 'gen:stop'`);
});
});
describe('gen:copy', function() {
it('should work', function() {
let source = factory.createForTest('doc.md', COPY_INPUT);
preprocessor([source]);
expect(source.hasUpdatedText()).toBe(true);
expect(source.text()).toBe(COPY_EXPECTED);
});
it('should throw if copy does not have argument', function() {
let source = factory.createForTest('doc.md', getCommand('copy()'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('should have argument');
});
it('should throw if copyId is not used', function() {
let source = factory.createForTest('doc.md', getCommand('copy(command-id)'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('unused copy id');
});
it('should throw if duplicate copy id', function() {
const copyCmd = getCommand('copy(foo)');
let source = factory.createForTest('doc.md', copyCmd + copyCmd);
let messages = preprocessor([source]);
messages.sort();
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(2);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('re-define copy id');
});
});
describe('gen:paste', function() {
it('should throw if paste does not have argument', function() {
let source = factory.createForTest('doc.md', getCommand('paste()'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('should have argument');
});
it('should throw if copyId is not defined', function() {
let source = factory.createForTest('doc.md', getCommand('paste(bar)'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('unknown copy id');
});
});
});
function getCommand(name, body = '') {