docs(new): add TSDoc comments to Puppeteer

new-docs/puppeteer.md

@@ -29,7 +29,7 @@
 |  [Keyboard](./puppeteer.keyboard.md) |  |
 |  [Mouse](./puppeteer.mouse.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 |
+|  [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class Puppeteer module provides a method to launch a Chromium instance. |
 |  [SecurityDetails](./puppeteer.securitydetails.md) |  |
 |  [Target](./puppeteer.target.md) |  |
 |  [TimeoutError](./puppeteer.timeouterror.md) |  |

new-docs/puppeteer.puppeteer.connect.md

@@ -4,6 +4,8 @@
 
 ## Puppeteer.connect() method
 
+This method attaches Puppeteer to an existing browser instance.
+
 <b>Signature:</b>
 
 ```typescript
@@ -19,9 +21,17 @@ connect(options: BrowserOptions & {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | BrowserOptions &amp; { browserWSEndpoint?: string; browserURL?: string; transport?: ConnectionTransport; product?: string; } |  |
+|  options | BrowserOptions &amp; { browserWSEndpoint?: string; browserURL?: string; transport?: ConnectionTransport; product?: string; } | Set of configurable options to set on the browser. |
 
 <b>Returns:</b>
 
 Promise&lt;[Browser](./puppeteer.browser.md)<!-- -->&gt;
 
+Promise which resolves to browser instance.
+
+## Remarks
+
+Options can have the following fields:
+
+- x `browserWSEndpoint` a browser websocket endpoint to connect to. - g `browserURL` a browser url to connect to, in format `http://${host}:${port}`<!-- -->. Use interchangeably with `browserWSEndpoint` to let Puppeteer fetch it from \[metadata endpoint\](https://chromedevtools.github.io/devtools-protocol/\#how-do-i-access-the-browser-target). - d `ignoreHTTPSErrors` Whether to ignore HTTPS errors during navigation. Defaults to `false`<!-- -->. - f `defaultViewport` Sets a consistent viewport for each page. Defaults to an 800x600 viewport. `null` disables the default viewport. - `width` page width in pixels. - `height` page height in pixels. - `deviceScaleFactor` Specify device scale factor (can be thought of as dpr). Defaults to `1`<!-- -->. - `isMobile` Whether the `meta viewport` tag is taken into account. Defaults to `false`<!-- -->. - `hasTouch` Specifies if viewport supports touch events. Defaults to `false` - `isLandscape` Specifies if viewport is in landscape mode. Defaults to `false`<!-- -->. - `slowMo` Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on. - `transport` \*\*Experimental\*\* Specify a custom transport object for Puppeteer to use. - `product` Possible values are: `chrome`<!-- -->, `firefox`<!-- -->. Defaults to `chrome`<!-- -->.
+

new-docs/puppeteer.puppeteer.launch.md

@@ -4,6 +4,8 @@
 
 ## Puppeteer.launch() method
 
+Launches puppeteer and launches a browser instance with given arguments and options when specified.
+
 <b>Signature:</b>
 
 ```typescript
@@ -17,9 +19,27 @@ launch(options?: LaunchOptions & ChromeArgOptions & BrowserOptions & {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | LaunchOptions &amp; ChromeArgOptions &amp; BrowserOptions &amp; { product?: string; extraPrefsFirefox?: {}; } |  |
+|  options | LaunchOptions &amp; ChromeArgOptions &amp; BrowserOptions &amp; { product?: string; extraPrefsFirefox?: {}; } | Set of configurable options to set on the browser. |
 
 <b>Returns:</b>
 
 Promise&lt;[Browser](./puppeteer.browser.md)<!-- -->&gt;
 
+Promise which resolves to browser instance.
+
+## Remarks
+
+`options` can have the following fields: - `product` Which browser to launch. At this time, this is either `chrome` or `firefox`<!-- -->. See also `PUPPETEER_PRODUCT`<!-- -->. - `ignoreHTTPSErrors` Whether to ignore HTTPS errors during navigation. Defaults to `false`<!-- -->. - `headless` Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome)<!-- -->. Defaults to `true` unless the `devtools` option is `true`<!-- -->. - `executablePath` Path to a browser executable to run instead of the bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd)<!-- -->. \*\*BEWARE\*\*: Puppeteer is only [guaranteed to work](https://github.com/puppeteer/puppeteer/#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy) with the bundled Chromium, use at your own risk. - `slowMo` Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on. - `defaultViewport` Sets a consistent viewport for each page. Defaults to an 800x600 viewport. `null` disables the default viewport. - `width` page width in pixels. - `height` page height in pixels. - `deviceScaleFactor` Specify device scale factor (can be thought of as dpr). Defaults to `1`<!-- -->. - `isMobile` Whether the `meta viewport` tag is taken into account. Defaults to `false`<!-- -->. - `hasTouch` Specifies if viewport supports touch events. Defaults to `false` - `isLandscape` Specifies if viewport is in landscape mode. Defaults to `false`<!-- -->. - `args` Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/)<!-- -->, and here is the list of [Firefox flags](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options)<!-- -->. - `ignoreDefaultArgs` If `true`<!-- -->, then do not use `puppeteer.defaultArgs()`<!-- -->. If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`<!-- -->. - `handleSIGINT` Close the browser process on Ctrl-C. Defaults to `true`<!-- -->. - `handleSIGTERM` Close the browser process on SIGTERM. Defaults to `true`<!-- -->. - `handleSIGHUP` Close the browser process on SIGHUP. Defaults to `true`<!-- -->. - `timeout` Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - `dumpio` Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`<!-- -->. Defaults to `false`<!-- -->. - `userDataDir` Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md)<!-- -->. - `env` Specify environment variables that will be visible to the browser. Defaults to `process.env`<!-- -->. - `devtools` Whether to auto-open a DevTools panel for each tab. If this option is `true`<!-- -->, the `headless` option will be set `false`<!-- -->. - `pipe` Connects to the browser over a pipe instead of a WebSocket. Defaults to `false`<!-- -->. - `extraPrefsFirefox` Additional [preferences](https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/Preference_reference) that can be passed to Firefox (see `PUPPETEER_PRODUCT`<!-- -->)
+
+## Example
+
+You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments:
+
+```js
+const browser = await puppeteer.launch({
+  ignoreDefaultArgs: ['--mute-audio']
+});
+
+```
+\*\*NOTE\*\* Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. In `puppeteer.launch([options])`<!-- -->, any mention of Chromium also applies to Chrome. See [this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
+

new-docs/puppeteer.puppeteer.md

@@ -4,19 +4,34 @@
 
 ## Puppeteer class
 
-The main Puppeteer class
+The main Puppeteer class Puppeteer module provides a method to launch a Chromium instance.
 
 <b>Signature:</b>
 
 ```typescript
 export declare class Puppeteer 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(projectRoot, preferredRevision, isPuppeteerCore, productName)](./puppeteer.puppeteer._constructor_.md) |  | Constructs a new instance of the <code>Puppeteer</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 `Puppeteer` class.
+
+## Example
+
+The following is a typical example of using Puppeteer to drive automation:
+
+```js
+const puppeteer = require('puppeteer');
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.goto('https://www.google.com');
+  // other actions...
+  await browser.close();
+})();
+
+```
 
 ## Properties
 
@@ -42,9 +57,9 @@ export declare class Puppeteer
 |  [\_\_experimental\_customQueryHandlers()](./puppeteer.puppeteer.__experimental_customqueryhandlers.md) |  |  |
 |  [\_\_experimental\_registerCustomQueryHandler(name, queryHandler)](./puppeteer.puppeteer.__experimental_registercustomqueryhandler.md) |  |  |
 |  [\_\_experimental\_unregisterCustomQueryHandler(name)](./puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md) |  |  |
-|  [connect(options)](./puppeteer.puppeteer.connect.md) |  |  |
+|  [connect(options)](./puppeteer.puppeteer.connect.md) |  | This method attaches Puppeteer to an existing browser instance. |
 |  [createBrowserFetcher(options)](./puppeteer.puppeteer.createbrowserfetcher.md) |  |  |
 |  [defaultArgs(options)](./puppeteer.puppeteer.defaultargs.md) |  |  |
 |  [executablePath()](./puppeteer.puppeteer.executablepath.md) |  |  |
-|  [launch(options)](./puppeteer.puppeteer.launch.md) |  |  |
+|  [launch(options)](./puppeteer.puppeteer.launch.md) |  | Launches puppeteer and launches a browser instance with given arguments and options when specified. |
 

src/Puppeteer.ts

@@ -37,6 +37,23 @@ import {
 
 /**
  * The main Puppeteer class
+ * Puppeteer module provides a method to launch a Chromium instance.
+ * 
+ * @remarks
+ * 
+ * @example
+ * The following is a typical example of using Puppeteer to drive automation:
+ * ```js
+ * const puppeteer = require('puppeteer');
+ *
+ * (async () => {
+ *   const browser = await puppeteer.launch();
+ *   const page = await browser.newPage();
+ *   await page.goto('https://www.google.com');
+ *   // other actions...
+ *   await browser.close();
+ * })();
+ * ```
  * @public
  */
 export class Puppeteer {
@@ -47,6 +64,9 @@ export class Puppeteer {
   __productName: string;
   _lazyLauncher: ProductLauncher;
 
+  /**
+   * @internal
+   */
   constructor(
     projectRoot: string,
     preferredRevision: string,
@@ -60,6 +80,27 @@ export class Puppeteer {
     this.__productName = productName;
   }
 
+  /**
+   * Launches puppeteer and launches a browser instance with given arguments and options when specified.
+   *
+   * @remarks
+   *
+   * @example
+   * You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments:
+   * ```js
+   * const browser = await puppeteer.launch({
+   *   ignoreDefaultArgs: ['--mute-audio']
+   * });
+   * ```
+   *
+   * **NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution.
+   * If Google Chrome (rather than Chromium) is preferred, a {@link https://www.google.com/chrome/browser/canary.html | Chrome Canary} or {@link https://www.chromium.org/getting-involved/dev-channel | Dev Channel} build is suggested.
+   * In `puppeteer.launch([options])`, any mention of Chromium also applies to Chrome.
+   * See {@link https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/ | this article} for a description of the differences between Chromium and Chrome. {@link https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md | This article} describes some differences for Linux users.
+   *
+   * @param options - Set of configurable options to set on the browser.
+   * @returns Promise which resolves to browser instance.
+   */
   launch(
     options: LaunchOptions &
       ChromeArgOptions &
@@ -69,6 +110,14 @@ export class Puppeteer {
     return this._launcher.launch(options);
   }
 
+  /**
+   * This method attaches Puppeteer to an existing browser instance.
+   *
+   * @remarks
+   *
+   * @param options - Set of configurable options to set on the browser.
+   * @returns Promise which resolves to browser instance.
+   */
   connect(
     options: BrowserOptions & {
       browserWSEndpoint?: string;
@@ -81,19 +130,35 @@ export class Puppeteer {
     return this._launcher.connect(options);
   }
 
+  /**
+   * @internal
+   */
   set _productName(name: string) {
     if (this.__productName !== name) this._changedProduct = true;
     this.__productName = name;
   }
 
+  /**
+   * @internal
+   */
   get _productName(): string {
     return this.__productName;
   }
 
+  /**
+   * @remarks
+   *
+   * **NOTE** `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH` and `PUPPETEER_CHROMIUM_REVISION` environment variables.
+   *
+   * @returns A path where Puppeteer expects to find the bundled browser. The browser binary might not be there if the download was skipped with the `PUPPETEER_SKIP_DOWNLOAD` environment variable.
+   */
   executablePath(): string {
     return this._launcher.executablePath();
   }
 
+  /**
+   * @internal
+   */
   get _launcher(): ProductLauncher {
     if (
       !this._lazyLauncher ||
@@ -122,26 +187,86 @@ export class Puppeteer {
     return this._lazyLauncher;
   }
 
+  /**
+   * @returns The name of the browser that is under automation (`"chrome"` or `"firefox"`)
+   *
+   * @remarks
+   * The product is set by the `PUPPETEER_PRODUCT` environment variable or the `product` option in `puppeteer.launch([options])` and defaults to `chrome`. Firefox support is experimental.
+   */
   get product(): string {
     return this._launcher.product;
   }
 
+  /**
+   * @remarks
+   * @example
+   *
+   * ```js
+   * const puppeteer = require('puppeteer');
+   * const iPhone = puppeteer.devices['iPhone 6'];
+   *
+   * (async () => {
+   *   const browser = await puppeteer.launch();
+   *   const page = await browser.newPage();
+   *   await page.emulate(iPhone);
+   *   await page.goto('https://www.google.com');
+   *   // other actions...
+   *   await browser.close();
+   * })();
+   * ```
+   * **NOTE** The old way (Puppeteer versions <= v1.14.0) devices can be obtained with `require('puppeteer/DeviceDescriptors')`.
+   *
+   * @returns a list of devices to be used with `page.emulate(options)`. Actual list of devices can be found in {@link https://github.com/puppeteer/puppeteer/blob/main/src/DeviceDescriptors.ts | src/DeviceDescriptors.js}.
+   */
   get devices(): DevicesMap {
     return devicesMap;
   }
 
+  /**
+   * @remarks
+   *
+   * Puppeteer methods might throw errors if they are unable to fulfill a request. For example, `page.waitForSelector(selector[, options])` might fail if the selector doesn't match any nodes during the given timeframe.
+   *
+   * For certain types of errors Puppeteer uses specific error classes. These classes are available via `puppeteer.errors`
+   * @example
+   * An example of handling a timeout error:
+   * ```js
+   * try {
+   *   await page.waitForSelector('.foo');
+   * } catch (e) {
+   *   if (e instanceof puppeteer.errors.TimeoutError) {
+   *     // Do something if this is a timeout.
+   *   }
+   * }
+   * ```
+   *
+   * **NOTE** The old way (Puppeteer versions <= v1.14.0) errors can be obtained with `require('puppeteer/Errors')`.
+   */
   get errors(): PuppeteerErrors {
     return puppeteerErrors;
   }
 
+  /**
+   *
+   * @param options Set of configurable options to set on the browser.
+   * @returns The default flags that Chromium will be launched with.
+   */
   defaultArgs(options: ChromeArgOptions): string[] {
     return this._launcher.defaultArgs(options);
   }
 
+  /**
+   *
+   * @param options Set of configurable options to specify the settings of the BrowserFetcher.
+   * @returns A new BrowserFetcher instance.
+   */
   createBrowserFetcher(options: BrowserFetcherOptions): BrowserFetcher {
     return new BrowserFetcher(this._projectRoot, options);
   }
 
+  /**
+   * @internal
+   */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_registerCustomQueryHandler(
     name: string,
@@ -150,16 +275,25 @@ export class Puppeteer {
     registerCustomQueryHandler(name, queryHandler);
   }
 
+  /**
+   * @internal
+   */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_unregisterCustomQueryHandler(name: string): void {
     unregisterCustomQueryHandler(name);
   }
 
+  /**
+   * @internal
+   */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_customQueryHandlers(): Map<string, QueryHandler> {
     return customQueryHandlers();
   }
 
+  /**
+   * @internal
+   */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_clearQueryHandlers(): void {
     clearQueryHandlers();