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.

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();
+})();
+
+```
+

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) |  |  |

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',

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',
         },
       ],
       [