From 13f8fe6e166ae82690b7dac484634f038b920aad Mon Sep 17 00:00:00 2001
From: Jack Franklin <jacktfranklin@chromium.org>
Date: Wed, 22 Jul 2020 10:04:53 +0100
Subject: [PATCH] chore(docs): `page.emulateVisionDeficiency` docs (#6231)

This commit also removes our own custom type for defining the vision
deficiencies and uses the protocol's type. Now we generate docs for
those we get the docs generated for free for these. This is better than
us duplicating values for types in doc comments and having them become
outdated. If we use the protocol types directly then we ensure we're up
to date and in-sync.

Long term the docs will also link to the devtools-protocol viewer.
---
 .../puppeteer.page.emulatevisiondeficiency.md | 31 ++++++++++++-
 new-docs/puppeteer.page.md                    |  2 +-
 src/common/Page.ts                            | 43 ++++++++++++++-----
 utils/doclint/check_public_api/index.js       |  2 +-
 4 files changed, 64 insertions(+), 14 deletions(-)

diff --git a/new-docs/puppeteer.page.emulatevisiondeficiency.md b/new-docs/puppeteer.page.emulatevisiondeficiency.md
index 2230df80256..2fc46cd7852 100644
--- a/new-docs/puppeteer.page.emulatevisiondeficiency.md
+++ b/new-docs/puppeteer.page.emulatevisiondeficiency.md
@@ -4,19 +4,46 @@
 
 ## Page.emulateVisionDeficiency() method
 
+Simulates the given vision deficiency on the page.
+
 <b>Signature:</b>
 
 ```typescript
-emulateVisionDeficiency(type?: VisionDeficiency): Promise<void>;
+emulateVisionDeficiency(type?: Protocol.Emulation.SetEmulatedVisionDeficiencyRequest['type']): Promise<void>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  type | VisionDeficiency |  |
+|  type | [Protocol.Emulation.SetEmulatedVisionDeficiencyRequest](./puppeteer.protocol.emulation.setemulatedvisiondeficiencyrequest.md)<!-- -->\['type'\] | the type of deficiency to simulate, or <code>'none'</code> to reset. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Example
+
+
+```js
+const puppeteer = require('puppeteer');
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.goto('https://v8.dev/blog/10-years');
+
+  await page.emulateVisionDeficiency('achromatopsia');
+  await page.screenshot({ path: 'achromatopsia.png' });
+
+  await page.emulateVisionDeficiency('deuteranopia');
+  await page.screenshot({ path: 'deuteranopia.png' });
+
+  await page.emulateVisionDeficiency('blurredVision');
+  await page.screenshot({ path: 'blurred-vision.png' });
+
+  await browser.close();
+})();
+
+```
+
diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md
index de70a41ee5c..6b23980db74 100644
--- a/new-docs/puppeteer.page.md
+++ b/new-docs/puppeteer.page.md
@@ -92,7 +92,7 @@ page.off('request', logRequest);
 |  [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) |  |  |
 |  [emulateMediaType(type)](./puppeteer.page.emulatemediatype.md) |  |  |
 |  [emulateTimezone(timezoneId)](./puppeteer.page.emulatetimezone.md) |  |  |
-|  [emulateVisionDeficiency(type)](./puppeteer.page.emulatevisiondeficiency.md) |  |  |
+|  [emulateVisionDeficiency(type)](./puppeteer.page.emulatevisiondeficiency.md) |  | Simulates the given vision deficiency on the page. |
 |  [evaluate(pageFunction, args)](./puppeteer.page.evaluate.md) |  |  |
 |  [evaluateHandle(pageFunction, args)](./puppeteer.page.evaluatehandle.md) |  |  |
 |  [evaluateOnNewDocument(pageFunction, args)](./puppeteer.page.evaluateonnewdocument.md) |  |  |
diff --git a/src/common/Page.ts b/src/common/Page.ts
index 6370ab5ccdd..4103862d914 100644
--- a/src/common/Page.ts
+++ b/src/common/Page.ts
@@ -152,14 +152,6 @@ interface ScreenshotOptions {
   encoding?: string;
 }
 
-type VisionDeficiency =
-  | 'none'
-  | 'achromatopsia'
-  | 'blurredVision'
-  | 'deuteranopia'
-  | 'protanopia'
-  | 'tritanopia';
-
 /**
  * All the events that a page instance may emit.
  *
@@ -1451,8 +1443,39 @@ export class Page extends EventEmitter {
     }
   }
 
-  async emulateVisionDeficiency(type?: VisionDeficiency): Promise<void> {
-    const visionDeficiencies = new Set([
+  /**
+   * Simulates the given vision deficiency on the page.
+   *
+   * @example
+   * ```js
+   * const puppeteer = require('puppeteer');
+   *
+   * (async () => {
+   *   const browser = await puppeteer.launch();
+   *   const page = await browser.newPage();
+   *   await page.goto('https://v8.dev/blog/10-years');
+   *
+   *   await page.emulateVisionDeficiency('achromatopsia');
+   *   await page.screenshot({ path: 'achromatopsia.png' });
+   *
+   *   await page.emulateVisionDeficiency('deuteranopia');
+   *   await page.screenshot({ path: 'deuteranopia.png' });
+   *
+   *   await page.emulateVisionDeficiency('blurredVision');
+   *   await page.screenshot({ path: 'blurred-vision.png' });
+   *
+   *   await browser.close();
+   * })();
+   * ```
+   *
+   * @param type - the type of deficiency to simulate, or `'none'` to reset.
+   */
+  async emulateVisionDeficiency(
+    type?: Protocol.Emulation.SetEmulatedVisionDeficiencyRequest['type']
+  ): Promise<void> {
+    const visionDeficiencies = new Set<
+      Protocol.Emulation.SetEmulatedVisionDeficiencyRequest['type']
+    >([
       'none',
       'achromatopsia',
       'blurredVision',
diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js
index fa8aa5c9fd0..f91205eaa20 100644
--- a/utils/doclint/check_public_api/index.js
+++ b/utils/doclint/check_public_api/index.js
@@ -653,7 +653,7 @@ function compareDocumentations(actual, expected) {
         'Method Page.emulateVisionDeficiency() type',
         {
           actualName: 'string',
-          expectedName: 'VisionDeficiency',
+          expectedName: 'Object',
         },
       ],
       [