feat(new-docs): migrate Dialog documentation to TSDoc (#5981)

new-docs/puppeteer.dialog._constructor_.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; [Dialog](./puppeteer.dialog.md) &gt; [(constructor)](./puppeteer.dialog._constructor_.md)
-
-## Dialog.(constructor)
-
-Constructs a new instance of the `Dialog` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(client: CDPSession, type: DialogType, message: string, defaultValue?: string);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  client | [CDPSession](./puppeteer.cdpsession.md) |  |
-|  type | [DialogType](./puppeteer.dialogtype.md) |  |
-|  message | string |  |
-|  defaultValue | string |  |
-

new-docs/puppeteer.dialog.accept.md

@@ -14,9 +14,11 @@ accept(promptText?: string): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  promptText | string |  |
+|  promptText | string | optional text that will be entered in the dialog prompt. Has no effect if the dialog's type is not <code>prompt</code>. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+A promise that resolves when the dialog has been accepted.
+

new-docs/puppeteer.dialog.defaultvalue.md

@@ -13,3 +13,5 @@ defaultValue(): string;
 
 string
 
+The default value of the prompt, or an empty string if the dialog is not a `prompt`<!-- -->.
+

new-docs/puppeteer.dialog.dismiss.md

@@ -13,3 +13,5 @@ dismiss(): Promise<void>;
 
 Promise&lt;void&gt;
 
+A promise which will resolve once the dialog has been dismissed
+

new-docs/puppeteer.dialog.md

@@ -4,23 +4,36 @@
 
 ## Dialog class
 
+Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the `dialog` event.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class Dialog 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(client, type, message, defaultValue)](./puppeteer.dialog._constructor_.md) |  | Constructs a new instance of the <code>Dialog</code> class |
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Dialog` class.
 
-## Properties
+## Example
 
-|  Property | Modifiers | Type | Description |
-|  --- | --- | --- | --- |
-|  [Type](./puppeteer.dialog.type.md) | <code>static</code> | typeof [DialogType](./puppeteer.dialogtype.md) |  |
+
+```js
+const puppeteer = require('puppeteer');
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  page.on('dialog', async dialog => {
+    console.log(dialog.message());
+    await dialog.dismiss();
+    await browser.close();
+  });
+  page.evaluate(() => alert('1'));
+})();
+
+```
 
 ## Methods
 

new-docs/puppeteer.dialog.message.md

@@ -13,3 +13,5 @@ message(): string;
 
 string
 
+The message displayed in the dialog.
+

new-docs/puppeteer.dialog.type.md

@@ -1,11 +1,17 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Dialog](./puppeteer.dialog.md) &gt; [Type](./puppeteer.dialog.type.md)
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Dialog](./puppeteer.dialog.md) &gt; [type](./puppeteer.dialog.type.md)
 
-## Dialog.Type property
+## Dialog.type() method
 
 <b>Signature:</b>
 
 ```typescript
-static Type: typeof DialogType;
+type(): Protocol.Page.DialogType;
 ```
+<b>Returns:</b>
+
+Protocol.Page.DialogType
+
+The type of the dialog.
+

new-docs/puppeteer.dialogtype.md

@@ -1,21 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [DialogType](./puppeteer.dialogtype.md)
-
-## DialogType enum
-
-<b>Signature:</b>
-
-```typescript
-export declare enum DialogType 
-```
-
-## Enumeration Members
-
-|  Member | Value | Description |
-|  --- | --- | --- |
-|  Alert | <code>&quot;alert&quot;</code> |  |
-|  BeforeUnload | <code>&quot;beforeunload&quot;</code> |  |
-|  Confirm | <code>&quot;confirm&quot;</code> |  |
-|  Prompt | <code>&quot;prompt&quot;</code> |  |
-

new-docs/puppeteer.md

@@ -16,7 +16,7 @@
 |  [Connection](./puppeteer.connection.md) |  |
 |  [ConsoleMessage](./puppeteer.consolemessage.md) |  |
 |  [Coverage](./puppeteer.coverage.md) |  |
-|  [Dialog](./puppeteer.dialog.md) |  |
+|  [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the <code>dialog</code> event. |
 |  [ElementHandle](./puppeteer.elementhandle.md) |  |
 |  [ExecutionContext](./puppeteer.executioncontext.md) |  |
 |  [FileChooser](./puppeteer.filechooser.md) |  |
@@ -36,12 +36,6 @@
 |  [Tracing](./puppeteer.tracing.md) |  |
 |  [WebWorker](./puppeteer.webworker.md) |  |
 
-## Enumerations
-
-|  Enumeration | Description |
-|  --- | --- |
-|  [DialogType](./puppeteer.dialogtype.md) |  |
-
 ## Functions
 
 |  Function | Description |

src/Dialog.ts

@@ -16,29 +16,42 @@
 
 import { assert } from './helper';
 import { CDPSession } from './Connection';
+import Protocol from './protocol';
 
-/* TODO(jacktfranklin): protocol.d.ts defines this
- * so let's ditch this and avoid the duplication
+/**
+ * Dialog instances are dispatched by the {@link Page} via the `dialog` event.
+ *
+ * @remarks
+ *
+ * @example
+ * ```js
+ * const puppeteer = require('puppeteer');
+ *
+ * (async () => {
+ *   const browser = await puppeteer.launch();
+ *   const page = await browser.newPage();
+ *   page.on('dialog', async dialog => {
+ *     console.log(dialog.message());
+ *     await dialog.dismiss();
+ *     await browser.close();
+ *   });
+ *   page.evaluate(() => alert('1'));
+ * })();
+ * ```
  */
-export enum DialogType {
-  Alert = 'alert',
-  BeforeUnload = 'beforeunload',
-  Confirm = 'confirm',
-  Prompt = 'prompt',
-}
-
 export class Dialog {
-  static Type = DialogType;
-
   private _client: CDPSession;
-  private _type: DialogType;
+  private _type: Protocol.Page.DialogType;
   private _message: string;
   private _defaultValue: string;
   private _handled = false;
 
+  /**
+   * @internal
+   */
   constructor(
     client: CDPSession,
-    type: DialogType,
+    type: Protocol.Page.DialogType,
     message: string,
     defaultValue = ''
   ) {
@@ -48,18 +61,31 @@ export class Dialog {
     this._defaultValue = defaultValue;
   }
 
-  type(): DialogType {
+  /**
+   * @returns The type of the dialog.
+   */
+  type(): Protocol.Page.DialogType {
     return this._type;
   }
 
+  /**
+   * @returns The message displayed in the dialog.
+   */
   message(): string {
     return this._message;
   }
 
+  /**
+   * @returns The default value of the prompt, or an empty string if the dialog is not a `prompt`.
+   */
   defaultValue(): string {
     return this._defaultValue;
   }
 
+  /**
+   * @param promptText - optional text that will be entered in the dialog prompt. Has no effect if the dialog's type is not `prompt`.
+   * @returns A promise that resolves when the dialog has been accepted.
+   */
   async accept(promptText?: string): Promise<void> {
     assert(!this._handled, 'Cannot accept dialog which is already handled!');
     this._handled = true;
@@ -69,6 +95,9 @@ export class Dialog {
     });
   }
 
+  /**
+   * @returns A promise which will resolve once the dialog has been dismissed
+   */
   async dismiss(): Promise<void> {
     assert(!this._handled, 'Cannot dismiss dialog which is already handled!');
     this._handled = true;

src/Page.ts

@@ -738,11 +738,16 @@ export class Page extends EventEmitter {
 
   _onDialog(event: Protocol.Page.javascriptDialogOpeningPayload): void {
     let dialogType = null;
-    if (event.type === 'alert') dialogType = Dialog.Type.Alert;
-    else if (event.type === 'confirm') dialogType = Dialog.Type.Confirm;
-    else if (event.type === 'prompt') dialogType = Dialog.Type.Prompt;
-    else if (event.type === 'beforeunload')
-      dialogType = Dialog.Type.BeforeUnload;
+    const validDialogTypes = new Set<Protocol.Page.DialogType>([
+      'alert',
+      'confirm',
+      'prompt',
+      'beforeunload',
+    ]);
+
+    if (validDialogTypes.has(event.type)) {
+      dialogType = event.type as Protocol.Page.DialogType;
+    }
     assert(dialogType, 'Unknown javascript dialog type: ' + event.type);
 
     const dialog = new Dialog(