docs(new): migrate Browser docs to TSDoc (#6070)

src/common/Browser.ts

@@ -27,7 +27,61 @@ import { Viewport } from './PuppeteerViewport';
 
 type BrowserCloseCallback = () => Promise<void> | void;
 
+/**
+ * @public
+ */
+export interface WaitForTargetOptions {
+  /**
+   * Maximum wait time in milliseconds. Pass `0` to disable the timeout.
+   * @defaultValue 30 seconds.
+   */
+  timeout?: number;
+}
+
+/**
+ * A Browser is created when Puppeteer connects to a Chromium instance, either through
+ * {@link Puppeteer.launch} or {@link Puppeteer.connect}.
+ *
+ * @example
+ *
+ * An example of using a {@link Browser} to create a {@link Page}:
+ * ```js
+ * const puppeteer = require('puppeteer');
+ *
+ * (async () => {
+ *   const browser = await puppeteer.launch();
+ *   const page = await browser.newPage();
+ *   await page.goto('https://example.com');
+ *   await browser.close();
+ * })();
+ * ```
+ *
+ * @example
+ *
+ * An example of disconnecting from and reconnecting to a {@link Browser}:
+ * ```js
+ * const puppeteer = require('puppeteer');
+ *
+ * (async () => {
+ *   const browser = await puppeteer.launch();
+ *   // Store the endpoint to be able to reconnect to Chromium
+ *   const browserWSEndpoint = browser.wsEndpoint();
+ *   // Disconnect puppeteer from Chromium
+ *   browser.disconnect();
+ *
+ *   // Use the endpoint to reestablish a connection
+ *   const browser2 = await puppeteer.connect({browserWSEndpoint});
+ *   // Close Chromium
+ *   await browser2.close();
+ * })();
+ * ```
+ *
+ * @public
+ */
 export class Browser extends EventEmitter {
+  /**
+   * @internal
+   */
   static async create(
     connection: Connection,
     contextIds: string[],
@@ -47,15 +101,22 @@ export class Browser extends EventEmitter {
     await connection.send('Target.setDiscoverTargets', { discover: true });
     return browser;
   }
-  _ignoreHTTPSErrors: boolean;
-  _defaultViewport?: Viewport;
-  _process?: ChildProcess;
-  _connection: Connection;
-  _closeCallback: BrowserCloseCallback;
-  _defaultContext: BrowserContext;
-  _contexts: Map<string, BrowserContext>;
+  private _ignoreHTTPSErrors: boolean;
+  private _defaultViewport?: Viewport;
+  private _process?: ChildProcess;
+  private _connection: Connection;
+  private _closeCallback: BrowserCloseCallback;
+  private _defaultContext: BrowserContext;
+  private _contexts: Map<string, BrowserContext>;
+  /**
+   * @internal
+   * Used in Target.ts directly so cannot be marked private.
+   */
   _targets: Map<string, Target>;
 
+  /**
+   * @internal
+   */
   constructor(
     connection: Connection,
     contextIds: string[],
@@ -94,10 +155,31 @@ export class Browser extends EventEmitter {
     );
   }
 
+  /**
+   * The spawned browser process. Returns `null` if the browser instance was created with
+   * {@link Puppeteer.connect}.
+   */
   process(): ChildProcess | null {
     return this._process;
   }
 
+  /**
+   * Creates a new incognito browser context. This won't share cookies/cache with other
+   * browser contexts.
+   *
+   * @example
+   * ```js
+   * (async () => {
+   *  const browser = await puppeteer.launch();
+   *   // Create a new incognito browser context.
+   *   const context = await browser.createIncognitoBrowserContext();
+   *   // Create a new page in a pristine context.
+   *   const page = await context.newPage();
+   *   // Do stuff
+   *   await page.goto('https://example.com');
+   * })();
+   * ```
+   */
   async createIncognitoBrowserContext(): Promise<BrowserContext> {
     const { browserContextId } = await this._connection.send(
       'Target.createBrowserContext'
@@ -111,16 +193,24 @@ export class Browser extends EventEmitter {
     return context;
   }
 
+  /**
+   * Returns an array of all open browser contexts. In a newly created browser, this will
+   * return a single instance of {@link BrowserContext}.
+   */
   browserContexts(): BrowserContext[] {
     return [this._defaultContext, ...Array.from(this._contexts.values())];
   }
 
+  /**
+   * Returns the default browser context. The default browser context cannot be closed.
+   */
   defaultBrowserContext(): BrowserContext {
     return this._defaultContext;
   }
 
   /**
-   * @param {?string} contextId
+   * @internal
+   * Used by BrowserContext directly so cannot be marked private.
    */
   async _disposeContext(contextId?: string): Promise<void> {
     await this._connection.send('Target.disposeBrowserContext', {
@@ -129,7 +219,7 @@ export class Browser extends EventEmitter {
     this._contexts.delete(contextId);
   }
 
-  async _targetCreated(
+  private async _targetCreated(
     event: Protocol.Target.targetCreatedPayload
   ): Promise<void> {
     const targetInfo = event.targetInfo;
@@ -158,10 +248,7 @@ export class Browser extends EventEmitter {
     }
   }
 
-  /**
-   * @param {{targetId: string}} event
-   */
-  async _targetDestroyed(event: { targetId: string }): Promise<void> {
+  private async _targetDestroyed(event: { targetId: string }): Promise<void> {
     const target = this._targets.get(event.targetId);
     target._initializedCallback(false);
     this._targets.delete(event.targetId);
@@ -174,10 +261,9 @@ export class Browser extends EventEmitter {
     }
   }
 
-  /**
-   * @param {!Protocol.Target.targetInfoChangedPayload} event
-   */
-  _targetInfoChanged(event: Protocol.Target.targetInfoChangedPayload): void {
+  private _targetInfoChanged(
+    event: Protocol.Target.targetInfoChangedPayload
+  ): void {
     const target = this._targets.get(event.targetInfo.targetId);
     assert(target, 'target should exist before targetInfoChanged');
     const previousURL = target.url();
@@ -189,14 +275,38 @@ export class Browser extends EventEmitter {
     }
   }
 
+  /**
+   * The browser websocket endpoint which can be used as an argument to
+   * {@link Puppeteer.connect}.
+   *
+   * @returns The Browser websocket url.
+   *
+   * @remarks
+   *
+   * The format is `ws://${host}:${port}/devtools/browser/<id>`.
+   *
+   * You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`.
+   * Learn more about the
+   * {@link https://chromedevtools.github.io/devtools-protocol | devtools protocol} and
+   * the {@link
+   * https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
+   * | browser endpoint}.
+   */
   wsEndpoint(): string {
     return this._connection.url();
   }
 
+  /**
+   * Creates a {@link Page} in the default browser context.
+   */
   async newPage(): Promise<Page> {
     return this._defaultContext.newPage();
   }
 
+  /**
+   * @internal
+   * Used by BrowserContext directly so cannot be marked private.
+   */
   async _createPageInContext(contextId?: string): Promise<Page> {
     const { targetId } = await this._connection.send('Target.createTarget', {
       url: 'about:blank',
@@ -211,24 +321,40 @@ export class Browser extends EventEmitter {
     return page;
   }
 
+  /**
+   * All active targets inside the Browser. In case of multiple browser contexts, returns
+   * an array with all the targets in all browser contexts.
+   */
   targets(): Target[] {
     return Array.from(this._targets.values()).filter(
       (target) => target._isInitialized
     );
   }
 
+  /**
+   * The target associated with the browser.
+   */
   target(): Target {
     return this.targets().find((target) => target.type() === 'browser');
   }
 
   /**
-   * @param {function(!Target):boolean} predicate
-   * @param {{timeout?: number}=} options
-   * @returns {!Promise<!Target>}
+   * Searches for a target in all browser contexts.
+   *
+   * @param predicate - A function to be run for every target.
+   * @returns The first target found that matches the `predicate` function.
+   *
+   * @example
+   *
+   * An example of finding a target for a page opened via `window.open`:
+   * ```js
+   * await page.evaluate(() => window.open('https://www.example.com/'));
+   * const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/');
+   * ```
    */
   async waitForTarget(
     predicate: (x: Target) => boolean,
-    options: { timeout?: number } = {}
+    options: WaitForTargetOptions = {}
   ): Promise<Target> {
     const { timeout = 30000 } = options;
     const existingTarget = this.targets().find(predicate);
@@ -254,6 +380,15 @@ export class Browser extends EventEmitter {
     }
   }
 
+  /**
+   * An array of all open pages inside the Browser.
+   *
+   * @remarks
+   *
+   * In case of multiple browser contexts, returns an array with all the pages in all
+   * browser contexts. Non-visible pages, such as `"background_page"`, will not be listed
+   * here. You can find them using {@link Target.page}.
+   */
   async pages(): Promise<Page[]> {
     const contextPages = await Promise.all(
       this.browserContexts().map((context) => context.pages())
@@ -262,30 +397,56 @@ export class Browser extends EventEmitter {
     return contextPages.reduce((acc, x) => acc.concat(x), []);
   }
 
+  /**
+   * A string representing the browser name and version.
+   *
+   * @remarks
+   *
+   * For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For
+   * non-headless, this is similar to `Chrome/61.0.3153.0`.
+   *
+   * The format of browser.version() might change with future releases of Chromium.
+   */
   async version(): Promise<string> {
     const version = await this._getVersion();
     return version.product;
   }
 
+  /**
+   * The browser's original user agent. Pages can override the browser user agent with
+   * {@link Page.setUserAgent}.
+   */
   async userAgent(): Promise<string> {
     const version = await this._getVersion();
     return version.userAgent;
   }
 
+  /**
+   * Closes Chromium and all of its pages (if any were opened). The {@link Browser} object
+   * itself is considered to be disposed and cannot be used anymore.
+   */
   async close(): Promise<void> {
     await this._closeCallback.call(null);
     this.disconnect();
   }
 
+  /**
+   * Disconnects Puppeteer from the browser, but leaves the Chromium process running.
+   * After calling `disconnect`, the {@link Browser} object is considered disposed and
+   * cannot be used anymore.
+   */
   disconnect(): void {
     this._connection.dispose();
   }
 
+  /**
+   * Indicates that the browser is connected.
+   */
   isConnected(): boolean {
     return !this._connection._closed;
   }
 
-  _getVersion(): Promise<Protocol.Browser.getVersionReturnValue> {
+  private _getVersion(): Promise<Protocol.Browser.getVersionReturnValue> {
     return this._connection.send('Browser.getVersion');
   }
 }