From 0820d48f804ce924af85fe160ea20a210f734046 Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <aslushnikov@gmail.com>
Date: Wed, 25 Apr 2018 18:18:08 -0700
Subject: [PATCH] chore: link to the latest-released API from the README.md
 (#2449)

This patch adds a preprocessor command to link to the latest-released
API from the README.md.

Fixes #1923.
---
 README.md                           |  2 +-
 utils/doclint/cli.js                |  6 ++++--
 utils/doclint/preprocessor/index.js |  4 ++++
 utils/doclint/preprocessor/test.js  | 26 ++++++++++++++++++++++++++
 4 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ba735604ee3..e366eadbd13 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 <img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right">
 
-###### [API](docs/api.md) | [FAQ](#faq) | [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md)
+###### <!-- gen:last-released-api -->[API](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md)<!-- gen:stop --> | [FAQ](#faq) | [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md)
 
 > Puppeteer is a Node library which provides a high-level API to control [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) Chrome or Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). It can also be configured to use full (non-headless) Chrome or Chromium.
 
diff --git a/utils/doclint/cli.js b/utils/doclint/cli.js
index 19b591f81b0..2b5ec98da7f 100755
--- a/utils/doclint/cli.js
+++ b/utils/doclint/cli.js
@@ -37,8 +37,10 @@ async function run() {
 
   // Documentation checks.
   {
-    const apiSource = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
-    const mdSources = [apiSource];
+    const mdSources = await Promise.all([
+      Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')),
+      Source.readFile(path.join(PROJECT_DIR, 'README.md'))
+    ]);
 
     const toc = require('./toc');
     messages.push(...await toc(mdSources));
diff --git a/utils/doclint/preprocessor/index.js b/utils/doclint/preprocessor/index.js
index da5aa96bac4..251b772b987 100644
--- a/utils/doclint/preprocessor/index.js
+++ b/utils/doclint/preprocessor/index.js
@@ -19,6 +19,8 @@ const Message = require('../Message');
 module.exports = function(sources, version) {
   // Release version is everything that doesn't include "-".
   const isReleaseVersion = !version.includes('-');
+  const lastReleasedAPILink = `[API](https://github.com/GoogleChrome/puppeteer/blob/v${version.split('-')[0]}/docs/api.md)`;
+
   const messages = [];
   const commands = [];
   for (const source of sources) {
@@ -52,6 +54,8 @@ module.exports = function(sources, version) {
       newText = isReleaseVersion ? 'v' + version : 'Tip-Of-Tree';
     else if (command.name === 'empty-if-release')
       newText = isReleaseVersion ? '' : command.originalText;
+    else if (command.name === 'last-released-api')
+      newText = lastReleasedAPILink;
     if (newText === null)
       messages.push(Message.error(`Unknown command 'gen:${command.name}'`));
     else if (applyCommand(command, newText))
diff --git a/utils/doclint/preprocessor/test.js b/utils/doclint/preprocessor/test.js
index 26c80c71d86..3b91c1724e9 100644
--- a/utils/doclint/preprocessor/test.js
+++ b/utils/doclint/preprocessor/test.js
@@ -100,6 +100,32 @@ describe('preprocessor', function() {
       `);
     });
   });
+  describe('gen:empty-if-release', function() {
+    it('should work with non-release version', function() {
+      const source = new Source('doc.md', `
+        <!-- gen:last-released-api -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([source], '1.3.0-post');
+      expect(messages.length).toBe(1);
+      expect(messages[0].type).toBe('warning');
+      expect(messages[0].text).toContain('doc.md');
+      expect(source.text()).toBe(`
+        <!-- gen:last-released-api -->[API](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md)<!-- gen:stop -->
+      `);
+    });
+    it('should work with release version', function() {
+      const source = new Source('doc.md', `
+        <!-- gen:last-released-api -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([source], '1.3.0');
+      expect(messages.length).toBe(1);
+      expect(messages[0].type).toBe('warning');
+      expect(messages[0].text).toContain('doc.md');
+      expect(source.text()).toBe(`
+        <!-- gen:last-released-api -->[API](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md)<!-- gen:stop -->
+      `);
+    });
+  });
   it('should work with multiple commands', function() {
     const source = new Source('doc.md', `
       <!-- gen:version -->XXX<!-- gen:stop -->