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.

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