chore(docs): fix DOMWorld doc warnings (#6166)

I noticed that DOMWorld was spitting a lot of warnings out when we
generated the docs. It was mostly easy tidy-ups and removing old JSDoc
comments and now the warnings are gone :)

new-docs/puppeteer.frame.goto.md

@@ -19,7 +19,7 @@ goto(url: string, options?: {
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  url | string |  |
-|  options | { referer?: string; timeout?: number; waitUntil?: PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\]; } |  |
+|  options | { referer?: string; timeout?: number; waitUntil?: [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)<!-- -->\[\]; } |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.frame.setcontent.md

@@ -18,7 +18,7 @@ setContent(html: string, options?: {
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  html | string |  |
-|  options | { timeout?: number; waitUntil?: PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\]; } |  |
+|  options | { timeout?: number; waitUntil?: [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)<!-- -->\[\]; } |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.frame.waitfornavigation.md

@@ -17,7 +17,7 @@ waitForNavigation(options?: {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { timeout?: number; waitUntil?: PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\]; } |  |
+|  options | { timeout?: number; waitUntil?: [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)<!-- -->\[\]; } |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.md

@@ -102,6 +102,7 @@
 |  [Platform](./puppeteer.platform.md) | Supported platforms. |
 |  [Product](./puppeteer.product.md) | Supported products. |
 |  [PuppeteerErrors](./puppeteer.puppeteererrors.md) |  |
+|  [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) |  |
 |  [Serializable](./puppeteer.serializable.md) |  |
 |  [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md) |  |
 |  [UnwrapElementHandle](./puppeteer.unwrapelementhandle.md) | Unwraps a DOM element out of an ElementHandle instance |

new-docs/puppeteer.puppeteerlifecycleevent.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)
+
+## PuppeteerLifeCycleEvent type
+
+<b>Signature:</b>
+
+```typescript
+export declare type PuppeteerLifeCycleEvent = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+```

new-docs/puppeteer.waitforoptions.md

@@ -16,5 +16,5 @@ export interface WaitForOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [timeout](./puppeteer.waitforoptions.timeout.md) | number | Maximum wait time in milliseconds, defaults to 30 seconds, pass <code>0</code> to disable the timeout. |
-|  [waitUntil](./puppeteer.waitforoptions.waituntil.md) | PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\] |  |
+|  [waitUntil](./puppeteer.waitforoptions.waituntil.md) | [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)<!-- -->\[\] |  |
 

src/api-docs-entry.ts

@@ -54,3 +54,5 @@ export * from './common/NetworkManager';
 export * from './common/WebWorker';
 export * from './common/USKeyboardLayout';
 export * from './common/EvalTypes';
+export * from './common/TimeoutSettings';
+export * from './common/LifecycleWatcher';

src/common/DOMWorld.ts

@@ -48,15 +48,18 @@ export interface WaitForSelectorOptions {
  * @internal
  */
 export class DOMWorld {
-  _frameManager: FrameManager;
-  _frame: Frame;
-  _timeoutSettings: TimeoutSettings;
-  _documentPromise?: Promise<ElementHandle> = null;
-  _contextPromise?: Promise<ExecutionContext> = null;
+  private _frameManager: FrameManager;
+  private _frame: Frame;
+  private _timeoutSettings: TimeoutSettings;
+  private _documentPromise?: Promise<ElementHandle> = null;
+  private _contextPromise?: Promise<ExecutionContext> = null;
 
-  _contextResolveCallback?: (x?: ExecutionContext) => void = null;
+  private _contextResolveCallback?: (x?: ExecutionContext) => void = null;
 
-  _detached = false;
+  private _detached = false;
+  /**
+   * internal
+   */
   _waitTasks = new Set<WaitTask>();
 
   constructor(
@@ -74,9 +77,6 @@ export class DOMWorld {
     return this._frame;
   }
 
-  /**
-   * @param {?ExecutionContext} context
-   */
   _setContext(context?: ExecutionContext): void {
     if (context) {
       this._contextResolveCallback.call(null, context);
@@ -102,9 +102,6 @@ export class DOMWorld {
       );
   }
 
-  /**
-   * @returns {!Promise<!ExecutionContext>}
-   */
   executionContext(): Promise<ExecutionContext> {
     if (this._detached)
       throw new Error(
@@ -121,11 +118,6 @@ export class DOMWorld {
     return context.evaluateHandle(pageFunction, ...args);
   }
 
-  /**
-   * @param {Function|string} pageFunction
-   * @param {!Array<*>} args
-   * @returns {!Promise<*>}
-   */
   async evaluate<ReturnType extends any>(
     pageFunction: Function | string,
     ...args: unknown[]
@@ -134,10 +126,6 @@ export class DOMWorld {
     return context.evaluate<ReturnType>(pageFunction, ...args);
   }
 
-  /**
-   * @param {string} selector
-   * @returns {!Promise<?ElementHandle>}
-   */
   async $(selector: string): Promise<ElementHandle | null> {
     const document = await this._document();
     const value = await document.$(selector);
@@ -188,10 +176,6 @@ export class DOMWorld {
     return value;
   }
 
-  /**
-   * @param {string} selector
-   * @returns {!Promise<!Array<!ElementHandle>>}
-   */
   async $$(selector: string): Promise<ElementHandle[]> {
     const document = await this._document();
     const value = await document.$$(selector);
@@ -249,8 +233,6 @@ export class DOMWorld {
    * You can pass a URL, filepath or string of contents. Note that when running Puppeteer
    * in a browser environment you cannot pass a filepath and should use either
    * `url` or `content`.
-   *
-   * @param options
    */
   async addScriptTag(options: {
     url?: string;
@@ -340,7 +322,6 @@ export class DOMWorld {
    * in a browser environment you cannot pass a filepath and should use either
    * `url` or `content`.
    *
-   * @param options
    */
   async addStyleTag(options: {
     url?: string;
@@ -541,13 +522,6 @@ export class DOMWorld {
     }
     return handle.asElement();
 
-    /**
-     * @param {string} selectorOrXPath
-     * @param {boolean} isXPath
-     * @param {boolean} waitForVisible
-     * @param {boolean} waitForHidden
-     * @returns {?Node|boolean}
-     */
     function predicate(
       selectorOrXPath: string,
       isXPath: boolean,

src/common/LifecycleWatcher.ts

@@ -43,6 +43,9 @@ const puppeteerToProtocolLifecycle = new Map<
   ['networkidle2', 'networkAlmostIdle'],
 ]);
 
+/**
+ * @internal
+ */
 export class LifecycleWatcher {
   _expectedLifecycle: ProtocolLifeCycleEvent[];
   _frameManager: FrameManager;

src/common/TimeoutSettings.ts

@@ -16,6 +16,9 @@
 
 const DEFAULT_TIMEOUT = 30000;
 
+/**
+ * @internal
+ */
 export class TimeoutSettings {
   _defaultTimeout: number | null;
   _defaultNavigationTimeout: number | null;
@@ -29,9 +32,6 @@ export class TimeoutSettings {
     this._defaultTimeout = timeout;
   }
 
-  /**
-   * @param {number} timeout
-   */
   setDefaultNavigationTimeout(timeout: number): void {
     this._defaultNavigationTimeout = timeout;
   }