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 · Jul 22, 2020 · 13f8fe6 · 13f8fe6
1 parent e3933dd
commit 13f8fe6
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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
@@ -653,7 +653,7 @@ function compareDocumentations(actual, expected) {
         'Method Page.emulateVisionDeficiency() type',
         {
           actualName: 'string',
-          expectedName: 'VisionDeficiency',
+          expectedName: 'Object',
         },
       ],
       [