docs(new): add TSDoc comments to Puppeteer (#6032)

new-docs/puppeteer.md

@@ -29,7 +29,7 @@
 |  [Keyboard](./puppeteer.keyboard.md) |  |
 |  [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. |
 |  [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 browser instance. |
 |  [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. |
 |  [Target](./puppeteer.target.md) |  |
 |  [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. |

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,14 @@ 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
+
+

new-docs/puppeteer.puppeteer.createbrowserfetcher.md

@@ -14,9 +14,11 @@ createBrowserFetcher(options: BrowserFetcherOptions): BrowserFetcher;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) |  |
+|  options | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | Set of configurable options to specify the settings of the BrowserFetcher. |
 
 <b>Returns:</b>
 
 [BrowserFetcher](./puppeteer.browserfetcher.md)
 
+A new BrowserFetcher instance.
+

new-docs/puppeteer.puppeteer.defaultargs.md

@@ -14,9 +14,11 @@ defaultArgs(options?: ChromeArgOptions): string[];
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | ChromeArgOptions |  |
+|  options | ChromeArgOptions | Set of configurable options to set on the browser. |
 
 <b>Returns:</b>
 
 string\[\]
 
+The default flags that Chromium will be launched with.
+

new-docs/puppeteer.puppeteer.devices.md

@@ -9,3 +9,25 @@
 ```typescript
 get devices(): DevicesMap;
 ```
+
+## 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();
+})();
+
+```
+

new-docs/puppeteer.puppeteer.errors.md

@@ -9,3 +9,25 @@
 ```typescript
 get errors(): PuppeteerErrors;
 ```
+
+## 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.
+  }
+}
+
+```
+

new-docs/puppeteer.puppeteer.executablepath.md

@@ -13,3 +13,9 @@ executablePath(): string;
 
 string
 
+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.
+
+## Remarks
+
+\*\*NOTE\*\* `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH` and `PUPPETEER_CHROMIUM_REVISION` environment variables.
+

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,26 @@ 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
+
+
+## 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 browser 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
 
@@ -25,10 +40,8 @@ export declare class Puppeteer
 |  [\_\_productName](./puppeteer.puppeteer.__productname.md) |  | string |  |
 |  [\_changedProduct](./puppeteer.puppeteer._changedproduct.md) |  | boolean |  |
 |  [\_isPuppeteerCore](./puppeteer.puppeteer._ispuppeteercore.md) |  | boolean |  |
-|  [\_launcher](./puppeteer.puppeteer._launcher.md) |  | ProductLauncher |  |
 |  [\_lazyLauncher](./puppeteer.puppeteer._lazylauncher.md) |  | ProductLauncher |  |
 |  [\_preferredRevision](./puppeteer.puppeteer._preferredrevision.md) |  | string |  |
-|  [\_productName](./puppeteer.puppeteer._productname.md) |  | string |  |
 |  [\_projectRoot](./puppeteer.puppeteer._projectroot.md) |  | string |  |
 |  [devices](./puppeteer.puppeteer.devices.md) |  | DevicesMap |  |
 |  [errors](./puppeteer.puppeteer.errors.md) |  | [PuppeteerErrors](./puppeteer.puppeteererrors.md) |  |
@@ -38,13 +51,9 @@ export declare class Puppeteer
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [\_\_experimental\_clearQueryHandlers()](./puppeteer.puppeteer.__experimental_clearqueryhandlers.md) |  |  |
-|  [\_\_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. |
 

new-docs/puppeteer.puppeteer.product.md

@@ -9,3 +9,8 @@
 ```typescript
 get product(): string;
 ```
+
+## 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.
+