docs(new): start documenting the Page class (#6001)

This PR starts exploring the Page class and how to best document it. It explores how best to document events in the system, and I think pulling them out into an `enum` is the best solution here. It lets us end up with a page of docs that explicitly lists all the events the page class can ever emit.

new-docs/puppeteer.md

@@ -27,7 +27,7 @@
 |  [JSHandle](./puppeteer.jshandle.md) |  |
 |  [Keyboard](./puppeteer.keyboard.md) |  |
 |  [Mouse](./puppeteer.mouse.md) |  |
-|  [Page](./puppeteer.page.md) |  |
+|  [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. |
 |  [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class |
 |  [SecurityDetails](./puppeteer.securitydetails.md) |  |
 |  [Target](./puppeteer.target.md) |  |
@@ -36,6 +36,12 @@
 |  [Tracing](./puppeteer.tracing.md) |  |
 |  [WebWorker](./puppeteer.webworker.md) |  |
 
+## Enumerations
+
+|  Enumeration | Description |
+|  --- | --- |
+|  [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. |
+
 ## Functions
 
 |  Function | Description |

new-docs/puppeteer.page._constructor_.md

@@ -1,22 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [(constructor)](./puppeteer.page._constructor_.md)
-
-## Page.(constructor)
-
-Constructs a new instance of the `Page` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  client | [CDPSession](./puppeteer.cdpsession.md) |  |
-|  target | [Target](./puppeteer.target.md) |  |
-|  ignoreHTTPSErrors | boolean |  |
-

new-docs/puppeteer.page._go.md

@@ -1,23 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_go](./puppeteer.page._go.md)
-
-## Page.\_go() method
-
-<b>Signature:</b>
-
-```typescript
-_go(delta: number, options: WaitForOptions): Promise<HTTPResponse | null>;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  delta | number |  |
-|  options | WaitForOptions |  |
-
-<b>Returns:</b>
-
-Promise&lt;[HTTPResponse](./puppeteer.httpresponse.md) \| null&gt;
-

new-docs/puppeteer.page._onlogentryadded.md

@@ -1,22 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_onLogEntryAdded](./puppeteer.page._onlogentryadded.md)
-
-## Page.\_onLogEntryAdded() method
-
-<b>Signature:</b>
-
-```typescript
-_onLogEntryAdded(event: Protocol.Log.entryAddedPayload): void;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  event | Protocol.Log.entryAddedPayload |  |
-
-<b>Returns:</b>
-
-void
-

new-docs/puppeteer.page._ontargetcrashed.md

@@ -1,15 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_onTargetCrashed](./puppeteer.page._ontargetcrashed.md)
-
-## Page.\_onTargetCrashed() method
-
-<b>Signature:</b>
-
-```typescript
-_onTargetCrashed(): void;
-```
-<b>Returns:</b>
-
-void
-

new-docs/puppeteer.page._screenshottask.md

@@ -1,23 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_screenshotTask](./puppeteer.page._screenshottask.md)
-
-## Page.\_screenshotTask() method
-
-<b>Signature:</b>
-
-```typescript
-_screenshotTask(format: 'png' | 'jpeg', options?: ScreenshotOptions): Promise<Buffer | string>;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  format | 'png' \| 'jpeg' |  |
-|  options | ScreenshotOptions |  |
-
-<b>Returns:</b>
-
-Promise&lt;Buffer \| string&gt;
-

new-docs/puppeteer.page.create.md

@@ -1,25 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [create](./puppeteer.page.create.md)
-
-## Page.create() method
-
-<b>Signature:</b>
-
-```typescript
-static create(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null): Promise<Page>;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  client | [CDPSession](./puppeteer.cdpsession.md) |  |
-|  target | [Target](./puppeteer.target.md) |  |
-|  ignoreHTTPSErrors | boolean |  |
-|  defaultViewport | Viewport \| null |  |
-
-<b>Returns:</b>
-
-Promise&lt;[Page](./puppeteer.page.md)<!-- -->&gt;
-

new-docs/puppeteer.page.md

@@ -4,17 +4,55 @@
 
 ## Page class
 
+Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class Page extends EventEmitter 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Page` class.
-|  --- | --- | --- |
+
-|  [(constructor)(client, target, ignoreHTTPSErrors)](./puppeteer.page._constructor_.md) |  | Constructs a new instance of the <code>Page</code> class |
+## Example 1
+
+This example creates a page, navigates it to a URL, and then \* saves a screenshot:
+
+```js
+const puppeteer = require('puppeteer');
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.goto('https://example.com');
+  await page.screenshot({path: 'screenshot.png'});
+  await browser.close();
+})();
+
+```
+The Page class emits various events which are documented in the [PageEmittedEvents](./puppeteer.pageemittedevents.md) enum.
+
+## Example 2
+
+This example logs a message for a single page `load` event:
+
+```js
+page.once('load', () => console.log('Page loaded!'));
+
+```
+To unsubscribe from events use the `off` method:
+
+```js
+function logRequest(interceptedRequest) {
+  console.log('A request was made:', interceptedRequest.url());
+}
+page.on('request', logRequest);
+// Sometime later...
+page.off('request', logRequest);
+
+```
 
 ## Properties
 
@@ -31,10 +69,6 @@ export declare class Page extends EventEmitter
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [\_go(delta, options)](./puppeteer.page._go.md) |  |  |
-|  [\_onLogEntryAdded(event)](./puppeteer.page._onlogentryadded.md) |  |  |
-|  [\_onTargetCrashed()](./puppeteer.page._ontargetcrashed.md) |  |  |
-|  [\_screenshotTask(format, options)](./puppeteer.page._screenshottask.md) |  |  |
 |  [$(selector)](./puppeteer.page._.md) |  |  |
 |  [$$(selector)](./puppeteer.page.__.md) |  |  |
 |  [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) |  |  |
@@ -50,7 +84,6 @@ export declare class Page extends EventEmitter
 |  [close(options)](./puppeteer.page.close.md) |  |  |
 |  [content()](./puppeteer.page.content.md) |  |  |
 |  [cookies(urls)](./puppeteer.page.cookies.md) |  |  |
-|  [create(client, target, ignoreHTTPSErrors, defaultViewport)](./puppeteer.page.create.md) | <code>static</code> |  |
 |  [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) |  |  |
 |  [emulate(options)](./puppeteer.page.emulate.md) |  |  |
 |  [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) |  |  |

new-docs/puppeteer.pageemittedevents.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PageEmittedEvents](./puppeteer.pageemittedevents.md)
+
+## PageEmittedEvents enum
+
+All the events that a page instance may emit.
+
+<b>Signature:</b>
+
+```typescript
+export declare const enum PageEmittedEvents 
+```
+
+## Enumeration Members
+
+|  Member | Value | Description |
+|  --- | --- | --- |
+|  WorkerCreated | <code>&quot;workercreated&quot;</code> | Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page. |
+

src/Page.ts

@@ -137,6 +137,17 @@ enum VisionDeficiency {
   tritanopia = 'tritanopia',
 }
 
+/**
+ * All the events that a page instance may emit.
+ */
+export const enum PageEmittedEvents {
+  /**
+   * Emitted when a dedicated {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker} is spawned by the page.
+   * @eventProperty
+   */
+  WorkerCreated = 'workercreated',
+}
+
 class ScreenshotTaskQueue {
   _chain: Promise<Buffer | string | void>;
 
@@ -153,7 +164,49 @@ class ScreenshotTaskQueue {
   }
 }
 
+/**
+ * Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] instance might have multiple [Page] instances.
+ *
+ * @remarks
+ *
+ * @example
+ * This example creates a page, navigates it to a URL, and then * saves a screenshot:
+ * ```js
+ * const puppeteer = require('puppeteer');
+ *
+ * (async () => {
+ *   const browser = await puppeteer.launch();
+ *   const page = await browser.newPage();
+ *   await page.goto('https://example.com');
+ *   await page.screenshot({path: 'screenshot.png'});
+ *   await browser.close();
+ * })();
+ * ```
+ *
+ * The Page class emits various events which are documented in the {@link PageEmittedEvents} enum.
+ *
+ * @example
+ * This example logs a message for a single page `load` event:
+ * ```js
+ * page.once('load', () => console.log('Page loaded!'));
+ * ```
+ *
+ * To unsubscribe from events use the `off` method:
+ *
+ * ```js
+ * function logRequest(interceptedRequest) {
+ *   console.log('A request was made:', interceptedRequest.url());
+ * }
+ * page.on('request', logRequest);
+ * // Sometime later...
+ * page.off('request', logRequest);
+ * ```
+ * @public
+ */
 export class Page extends EventEmitter {
+  /**
+   * @internal
+   */
   static async create(
     client: CDPSession,
     target: Target,
@@ -188,6 +241,9 @@ export class Page extends EventEmitter {
 
   private _disconnectPromise?: Promise<Error>;
 
+  /**
+   * @internal
+   */
   constructor(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean) {
     super();
     this._client = client;
@@ -226,7 +282,7 @@ export class Page extends EventEmitter {
         this._handleException.bind(this)
       );
       this._workers.set(event.sessionId, worker);
-      this.emit(Events.Page.WorkerCreated, worker);
+      this.emit(PageEmittedEvents.WorkerCreated, worker);
     });
     client.on('Target.detachedFromTarget', (event) => {
       const worker = this._workers.get(event.sessionId);
@@ -371,11 +427,11 @@ export class Page extends EventEmitter {
     return this._target.browserContext();
   }
 
-  _onTargetCrashed(): void {
+  private _onTargetCrashed(): void {
     this.emit('error', new Error('Page crashed!'));
   }
 
-  _onLogEntryAdded(event: Protocol.Log.entryAddedPayload): void {
+  private _onLogEntryAdded(event: Protocol.Log.entryAddedPayload): void {
     const { level, text, args, source, url, lineNumber } = event.entry;
     if (args) args.map((arg) => helper.releaseObject(this._client, arg));
     if (source !== 'worker')
@@ -859,7 +915,7 @@ export class Page extends EventEmitter {
     return this._go(+1, options);
   }
 
-  async _go(
+  private async _go(
     delta: number,
     options: WaitForOptions
   ): Promise<HTTPResponse | null> {
@@ -1072,7 +1128,7 @@ export class Page extends EventEmitter {
     );
   }
 
-  async _screenshotTask(
+  private async _screenshotTask(
     format: 'png' | 'jpeg',
     options?: ScreenshotOptions
   ): Promise<Buffer | string> {