diff --git a/docs/api.md b/docs/api.md index 097e8ecc262..ed432b35851 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,9 +1,13 @@ ##### Released APIs: [v1.3.0](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md) | [v1.2.0](https://github.com/GoogleChrome/puppeteer/blob/v1.2.0/docs/api.md) | [v1.1.1](https://github.com/GoogleChrome/puppeteer/blob/v1.1.1/docs/api.md) | [v1.1.0](https://github.com/GoogleChrome/puppeteer/blob/v1.1.0/docs/api.md) | [v1.0.0](https://github.com/GoogleChrome/puppeteer/blob/v1.0.0/docs/api.md) | [v0.13.0](https://github.com/GoogleChrome/puppeteer/blob/v0.13.0/docs/api.md) | [v0.12.0](https://github.com/GoogleChrome/puppeteer/blob/v0.12.0/docs/api.md) | [v0.11.0](https://github.com/GoogleChrome/puppeteer/blob/v0.11.0/docs/api.md) | [v0.10.2](https://github.com/GoogleChrome/puppeteer/blob/v0.10.2/docs/api.md) | [v0.10.1](https://github.com/GoogleChrome/puppeteer/blob/v0.10.1/docs/api.md) | [v0.10.0](https://github.com/GoogleChrome/puppeteer/blob/v0.10.0/docs/api.md) | [v0.9.0](https://github.com/GoogleChrome/puppeteer/blob/v0.9.0/docs/api.md) -# Puppeteer API v1.3.0-post +# Puppeteer API Tip-Of-Tree + + > Next Release: **May 8, 2018** + + ##### Table of Contents diff --git a/utils/doclint/cli.js b/utils/doclint/cli.js index 9271c64ebfd..296b05f48ad 100755 --- a/utils/doclint/cli.js +++ b/utils/doclint/cli.js @@ -20,6 +20,7 @@ const path = require('path'); const SourceFactory = require('./SourceFactory'); const PROJECT_DIR = path.join(__dirname, '..', '..'); +const VERSION = require(path.join(PROJECT_DIR, 'package.json')).version; const RED_COLOR = '\x1b[31m'; const YELLOW_COLOR = '\x1b[33m'; @@ -43,7 +44,7 @@ async function run() { messages.push(...await toc(mdSources)); const preprocessor = require('./preprocessor'); - messages.push(...await preprocessor(mdSources)); + messages.push(...await preprocessor(mdSources, VERSION)); const browser = await puppeteer.launch({args: ['--no-sandbox']}); const page = await browser.newPage(); diff --git a/utils/doclint/preprocessor/index.js b/utils/doclint/preprocessor/index.js index 061a10f9774..da5aa96bac4 100644 --- a/utils/doclint/preprocessor/index.js +++ b/utils/doclint/preprocessor/index.js @@ -16,14 +16,14 @@ const Message = require('../Message'); -const PUPPETEER_VERSION = require('../../../package.json').version; - -module.exports = function(sources) { +module.exports = function(sources, version) { + // Release version is everything that doesn't include "-". + const isReleaseVersion = !version.includes('-'); const messages = []; - let commands = []; + const commands = []; for (const source of sources) { const text = source.text(); - const commandStartRegex = //ig; + const commandStartRegex = //ig; const commandEndRegex = //ig; let start; @@ -32,27 +32,29 @@ module.exports = function(sources) { const end = commandEndRegex.exec(text); if (!end) { messages.push(Message.error(`Failed to find 'gen:stop' for command ${start[0]}`)); - break; + return messages; } const name = start[1]; - const arg = start[2]; const from = commandStartRegex.lastIndex; const to = end.index; + const originalText = text.substring(from, to); + commands.push({name, from, to, originalText, source}); commandStartRegex.lastIndex = commandEndRegex.lastIndex; - commands.push({name, arg, from, to, source}); } } - commands = validateCommands(commands, messages); - const changedSources = new Set(); // Iterate commands in reverse order so that edits don't conflict. commands.sort((a, b) => b.from - a.from); for (const command of commands) { - let newText = command.source.text(); + let newText = null; if (command.name === 'version') - newText = replaceInText(newText, command.from, command.to, PUPPETEER_VERSION); - if (command.source.setText(newText)) + newText = isReleaseVersion ? 'v' + version : 'Tip-Of-Tree'; + else if (command.name === 'empty-if-release') + newText = isReleaseVersion ? '' : command.originalText; + if (newText === null) + messages.push(Message.error(`Unknown command 'gen:${command.name}'`)); + else if (applyCommand(command, newText)) changedSources.add(command.source); } for (const source of changedSources) @@ -61,35 +63,13 @@ module.exports = function(sources) { }; /** - * @param {!Array} commands - * @param {!Array} outMessages - * @return {!Array} + * @param {{name: string, from: number, to: number, source: !Source}} command + * @param {string} editText + * @return {boolean} */ -function validateCommands(commands, outMessages) { - // Filter sane commands - const goodCommands = commands.filter(command => { - if (command.name === 'version') - return check(command, !command.arg, `"gen:version" should not have argument`); - check(command, false, `Unknown command: "gen:${command.name}"`); - }); - - return goodCommands; - - function check(command, condition, message) { - if (condition) - return true; - outMessages.push(Message.error(`${command.source.projectPath()}: ${message}`)); - return false; - } +function applyCommand(command, editText) { + const text = command.source.text(); + const newText = text.substring(0, command.from) + editText + text.substring(command.to); + return command.source.setText(newText); } -/** - * @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); -} diff --git a/utils/doclint/preprocessor/test.js b/utils/doclint/preprocessor/test.js index a260c2439ed..41401c63bef 100644 --- a/utils/doclint/preprocessor/test.js +++ b/utils/doclint/preprocessor/test.js @@ -17,7 +17,6 @@ const preprocessor = require('.'); const SourceFactory = require('../SourceFactory'); const factory = new SourceFactory(); -const VERSION = require('../../../package.json').version; const {TestRunner, Reporter, Matchers} = require('../../testrunner/'); const runner = new TestRunner(); @@ -30,8 +29,10 @@ const {expect} = new Matchers(); describe('preprocessor', function() { it('should throw for unknown command', function() { - const source = factory.createForTest('doc.md', getCommand('unknownCommand()')); - const messages = preprocessor([source]); + const source = factory.createForTest('doc.md', ` + something + `); + const messages = preprocessor([source], '1.1.1'); expect(source.hasUpdatedText()).toBe(false); expect(messages.length).toBe(1); expect(messages[0].type).toBe('error'); @@ -39,32 +40,85 @@ describe('preprocessor', function() { }); describe('gen:version', function() { it('should work', function() { - const source = factory.createForTest('doc.md', `Puppeteer v${getCommand('version')}`); - const messages = preprocessor([source]); + const source = factory.createForTest('doc.md', ` + Puppeteer XXX + `); + const messages = preprocessor([source], '1.2.0'); expect(messages.length).toBe(1); expect(messages[0].type).toBe('warning'); expect(messages[0].text).toContain('doc.md'); - expect(source.text()).toBe(`Puppeteer v${getCommand('version', VERSION)}`); + expect(source.text()).toBe(` + Puppeteer v1.2.0 + `); + }); + it('should work for *-post versions', function() { + const source = factory.createForTest('doc.md', ` + Puppeteer XXX + `); + const messages = preprocessor([source], '1.2.0-post'); + expect(messages.length).toBe(1); + expect(messages[0].type).toBe('warning'); + expect(messages[0].text).toContain('doc.md'); + expect(source.text()).toBe(` + Puppeteer Tip-Of-Tree + `); }); it('should tolerate different writing', function() { - const source = factory.createForTest('doc.md', `Puppeteer vWHAT + const source = factory.createForTest('doc.md', `Puppeteer vWHAT `); - preprocessor([source]); - expect(source.text()).toBe(`Puppeteer v${VERSION}`); + preprocessor([source], '1.1.1'); + expect(source.text()).toBe(`Puppeteer vv1.1.1`); }); it('should not tolerate missing gen:stop', function() { const source = factory.createForTest('doc.md', ``); - const messages = preprocessor([source]); + const messages = preprocessor([source], '1.2.0'); expect(source.hasUpdatedText()).toBe(false); expect(messages.length).toBe(1); expect(messages[0].type).toBe('error'); expect(messages[0].text).toContain(`Failed to find 'gen:stop'`); }); }); + describe('gen:empty-if-release', function() { + it('should clear text when release version', function() { + const source = factory.createForTest('doc.md', ` + XXX + `); + const messages = preprocessor([source], '1.1.1'); + expect(messages.length).toBe(1); + expect(messages[0].type).toBe('warning'); + expect(messages[0].text).toContain('doc.md'); + expect(source.text()).toBe(` + + `); + }); + it('should keep text when non-release version', function() { + const source = factory.createForTest('doc.md', ` + XXX + `); + const messages = preprocessor([source], '1.1.1-post'); + expect(messages.length).toBe(0); + expect(source.text()).toBe(` + XXX + `); + }); + }); + it('should work with multiple commands', function() { + const source = factory.createForTest('doc.md', ` + XXX + YYY + ZZZ + `); + const messages = preprocessor([source], '1.1.1'); + expect(messages.length).toBe(1); + expect(messages[0].type).toBe('warning'); + expect(messages[0].text).toContain('doc.md'); + expect(source.text()).toBe(` + v1.1.1 + + v1.1.1 + `); + }); }); runner.run(); -function getCommand(name, body = '') { - return `${body}`; -}