docs(new): add TSDoc comments to BrowserContext (#6066)

new-docs/puppeteer.browsercontext._browser.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [\_browser](./puppeteer.browsercontext._browser.md)
-
-## BrowserContext.\_browser property
-
-<b>Signature:</b>
-
-```typescript
-_browser: Browser;
-```

new-docs/puppeteer.browsercontext._connection.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [\_connection](./puppeteer.browsercontext._connection.md)
-
-## BrowserContext.\_connection property
-
-<b>Signature:</b>
-
-```typescript
-_connection: Connection;
-```

new-docs/puppeteer.browsercontext._constructor_.md

@@ -1,22 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [(constructor)](./puppeteer.browsercontext._constructor_.md)
-
-## BrowserContext.(constructor)
-
-Constructs a new instance of the `BrowserContext` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(connection: Connection, browser: Browser, contextId?: string);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  connection | [Connection](./puppeteer.connection.md) |  |
-|  browser | [Browser](./puppeteer.browser.md) |  |
-|  contextId | string |  |
-

new-docs/puppeteer.browsercontext._id.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [\_id](./puppeteer.browsercontext._id.md)
-
-## BrowserContext.\_id property
-
-<b>Signature:</b>
-
-```typescript
-_id?: string;
-```

new-docs/puppeteer.browsercontext.browser.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.browser() method
 
+The browser this browser context belongs to.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.browsercontext.clearpermissionoverrides.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.clearPermissionOverrides() method
 
+Clears all permission overrides for the browser context.
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,14 @@ clearPermissionOverrides(): Promise<void>;
 
 Promise&lt;void&gt;
 
+## Example
+
+
+```js
+const context = browser.defaultBrowserContext();
+context.overridePermissions('https://example.com', ['clipboard-read']);
+// do stuff ..
+context.clearPermissionOverrides();
+
+```
+

new-docs/puppeteer.browsercontext.close.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.close() method
 
+Closes the browser context. All the targets that belong to the browser context will be closed.
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,7 @@ close(): Promise<void>;
 
 Promise&lt;void&gt;
 
+## Remarks
+
+Only incognito browser contexts can be closed.
+

new-docs/puppeteer.browsercontext.isincognito.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.isIncognito() method
 
+Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context.
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,7 @@ isIncognito(): boolean;
 
 boolean
 
+## Remarks
+
+The default browser context cannot be closed.
+

new-docs/puppeteer.browsercontext.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext class
 
+BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context.
+
 <b>Signature:</b>
 
 ```typescript
@@ -11,31 +13,40 @@ export declare class BrowserContext extends EventEmitter
 ```
 <b>Extends:</b> [EventEmitter](./puppeteer.eventemitter.md)
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser context.
-|  --- | --- | --- |
-|  [(constructor)(connection, browser, contextId)](./puppeteer.browsercontext._constructor_.md) |  | Constructs a new instance of the <code>BrowserContext</code> class |
 
-## Properties
+Puppeteer allows creation of "incognito" browser contexts with [Browser.createIncognitoBrowserContext](./puppeteer.browser.createincognitobrowsercontext.md) method. "Incognito" browser contexts don't write any browsing data to disk.
 
-|  Property | Modifiers | Type | Description |
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BrowserContext` class.
-|  --- | --- | --- | --- |
+
-|  [\_browser](./puppeteer.browsercontext._browser.md) |  | [Browser](./puppeteer.browser.md) |  |
+## Example
-|  [\_connection](./puppeteer.browsercontext._connection.md) |  | [Connection](./puppeteer.connection.md) |  |
+
-|  [\_id](./puppeteer.browsercontext._id.md) |  | string |  |
+
+```js
+// Create a new incognito browser context
+const context = await browser.createIncognitoBrowserContext();
+// Create a new page inside context.
+const page = await context.newPage();
+// ... do stuff with page ...
+await page.goto('https://example.com');
+// Dispose context once it's no longer needed.
+await context.close();
+
+```
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [browser()](./puppeteer.browsercontext.browser.md) |  |  |
+|  [browser()](./puppeteer.browsercontext.browser.md) |  | The browser this browser context belongs to. |
-|  [clearPermissionOverrides()](./puppeteer.browsercontext.clearpermissionoverrides.md) |  |  |
+|  [clearPermissionOverrides()](./puppeteer.browsercontext.clearpermissionoverrides.md) |  | Clears all permission overrides for the browser context. |
-|  [close()](./puppeteer.browsercontext.close.md) |  |  |
+|  [close()](./puppeteer.browsercontext.close.md) |  | Closes the browser context. All the targets that belong to the browser context will be closed. |
-|  [isIncognito()](./puppeteer.browsercontext.isincognito.md) |  |  |
+|  [isIncognito()](./puppeteer.browsercontext.isincognito.md) |  | Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context. |
-|  [newPage()](./puppeteer.browsercontext.newpage.md) |  |  |
+|  [newPage()](./puppeteer.browsercontext.newpage.md) |  | Creates a new page in the browser context. |
 |  [overridePermissions(origin, permissions)](./puppeteer.browsercontext.overridepermissions.md) |  |  |
-|  [pages()](./puppeteer.browsercontext.pages.md) |  |  |
+|  [pages()](./puppeteer.browsercontext.pages.md) |  | An array of all pages inside the browser context. |
-|  [targets()](./puppeteer.browsercontext.targets.md) |  |  |
+|  [targets()](./puppeteer.browsercontext.targets.md) |  | An array of all active targets inside the browser context. |
-|  [waitForTarget(predicate, options)](./puppeteer.browsercontext.waitfortarget.md) |  |  |
+|  [waitForTarget(predicate, options)](./puppeteer.browsercontext.waitfortarget.md) |  | This searches for a target in this specific browser context. |
 

new-docs/puppeteer.browsercontext.newpage.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.newPage() method
 
+Creates a new page in the browser context.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.browsercontext.overridepermissions.md

@@ -14,10 +14,19 @@ overridePermissions(origin: string, permissions: Protocol.Browser.PermissionType
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  origin | string |  |
+|  origin | string | The origin to grant permissions to, e.g. "https://example.com". |
-|  permissions | Protocol.Browser.PermissionType\[\] |  |
+|  permissions | Protocol.Browser.PermissionType\[\] | An array of permissions to grant. All permissions that are not listed here will be automatically denied. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Example
+
+
+```js
+const context = browser.defaultBrowserContext();
+await context.overridePermissions('https://html5demos.com', ['geolocation']);
+
+```
+

new-docs/puppeteer.browsercontext.pages.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.pages() method
 
+An array of all pages inside the browser context.
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,5 @@ pages(): Promise<Page[]>;
 
 Promise&lt;[Page](./puppeteer.page.md)<!-- -->\[\]&gt;
 
+Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`<!-- -->, will not be listed here. You can find them using [the target page](./puppeteer.target.page.md)<!-- -->.
+

new-docs/puppeteer.browsercontext.targets.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.targets() method
 
+An array of all active targets inside the browser context.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.browsercontext.waitfortarget.md

@@ -4,6 +4,8 @@
 
 ## BrowserContext.waitForTarget() method
 
+This searches for a target in this specific browser context.
+
 <b>Signature:</b>
 
 ```typescript
@@ -16,10 +18,22 @@ waitForTarget(predicate: (x: Target) => boolean, options: {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; boolean |  |
+|  predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; boolean | A function to be run for every target |
-|  options | { timeout?: number; } |  |
+|  options | { timeout?: number; } | An object of options. Accepts a timout, which is the maximum wait time in milliseconds. Pass <code>0</code> to disable the timeout. Defaults to 30 seconds. |
 
 <b>Returns:</b>
 
 Promise&lt;[Target](./puppeteer.target.md)<!-- -->&gt;
 
+Promise which resolves to 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 browserContext.waitForTarget(target => target.url() === 'https://www.example.com/');
+
+```
+

new-docs/puppeteer.md

@@ -10,7 +10,7 @@
 |  --- | --- |
 |  [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access)<!-- -->. |
 |  [Browser](./puppeteer.browser.md) | A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->. |
-|  [BrowserContext](./puppeteer.browsercontext.md) |  |
+|  [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. |
 |  [BrowserFetcher](./puppeteer.browserfetcher.md) |  |
 |  [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. |
 |  [Connection](./puppeteer.connection.md) |  |

src/common/Browser.ts

@@ -451,11 +451,41 @@ export class Browser extends EventEmitter {
   }
 }
 
+/**
+ * BrowserContexts provide a way to operate multiple independent browser sessions.
+ * When a browser is launched, it has a single BrowserContext used by default.
+ * The method {@link Browser.newPage | Browser.newPage} creates a page
+ * in the default browser context.
+ *
+ * @remarks
+ *
+ * If a page opens another page, e.g. with a `window.open` call,
+ * the popup will belong to the parent page's browser context.
+ *
+ * Puppeteer allows creation of "incognito" browser contexts with
+ * {@link Browser.createIncognitoBrowserContext | Browser.createIncognitoBrowserContext}
+ * method. "Incognito" browser contexts don't write any browsing data to disk.
+ *
+ * @example
+ * ```js
+ * // Create a new incognito browser context
+ * const context = await browser.createIncognitoBrowserContext();
+ * // Create a new page inside context.
+ * const page = await context.newPage();
+ * // ... do stuff with page ...
+ * await page.goto('https://example.com');
+ * // Dispose context once it's no longer needed.
+ * await context.close();
+ * ```
+ */
 export class BrowserContext extends EventEmitter {
-  _connection: Connection;
+  private _connection: Connection;
-  _browser: Browser;
+  private _browser: Browser;
-  _id?: string;
+  private _id?: string;
 
+  /**
+   * @internal
+   */
   constructor(connection: Connection, browser: Browser, contextId?: string) {
     super();
     this._connection = connection;
@@ -463,12 +493,32 @@ export class BrowserContext extends EventEmitter {
     this._id = contextId;
   }
 
+  /**
+   * An array of all active targets inside the browser context.
+   */
   targets(): Target[] {
     return this._browser
       .targets()
       .filter((target) => target.browserContext() === this);
   }
 
+  /**
+   * This searches for a target in this specific browser context.
+   *
+   * @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 browserContext.waitForTarget(target => target.url() === 'https://www.example.com/');
+   * ```
+   *
+   * @param predicate - A function to be run for every target
+   * @param options - An object of options. Accepts a timout,
+   * which is the maximum wait time in milliseconds.
+   * Pass `0` to disable the timeout. Defaults to 30 seconds.
+   * @returns Promise which resolves to the first target found
+   * that matches the `predicate` function.
+   */
   waitForTarget(
     predicate: (x: Target) => boolean,
     options: { timeout?: number } = {}
@@ -479,6 +529,13 @@ export class BrowserContext extends EventEmitter {
     );
   }
 
+  /**
+   * An array of all pages inside the browser context.
+   *
+   * @returns Promise which resolves to an array of all open pages.
+   * Non visible pages, such as `"background_page"`, will not be listed here.
+   * You can find them using {@link Target.page | the target page}.
+   */
   async pages(): Promise<Page[]> {
     const pages = await Promise.all(
       this.targets()
@@ -488,10 +545,28 @@ export class BrowserContext extends EventEmitter {
     return pages.filter((page) => !!page);
   }
 
+  /**
+   * Returns whether BrowserContext is incognito.
+   * The default browser context is the only non-incognito browser context.
+   *
+   * @remarks
+   * The default browser context cannot be closed.
+   */
   isIncognito(): boolean {
     return !!this._id;
   }
 
+  /**
+   * @example
+   * ```js
+   * const context = browser.defaultBrowserContext();
+   * await context.overridePermissions('https://html5demos.com', ['geolocation']);
+   * ```
+   *
+   * @param origin - The origin to grant permissions to, e.g. "https://example.com".
+   * @param permissions - An array of permissions to grant.
+   * All permissions that are not listed here will be automatically denied.
+   */
   async overridePermissions(
     origin: string,
     permissions: Protocol.Browser.PermissionType[]
@@ -532,20 +607,44 @@ export class BrowserContext extends EventEmitter {
     });
   }
 
+  /**
+   * Clears all permission overrides for the browser context.
+   *
+   * @example
+   * ```js
+   * const context = browser.defaultBrowserContext();
+   * context.overridePermissions('https://example.com', ['clipboard-read']);
+   * // do stuff ..
+   * context.clearPermissionOverrides();
+   * ```
+   */
   async clearPermissionOverrides(): Promise<void> {
     await this._connection.send('Browser.resetPermissions', {
       browserContextId: this._id || undefined,
     });
   }
 
+  /**
+   * Creates a new page in the browser context.
+   */
   newPage(): Promise<Page> {
     return this._browser._createPageInContext(this._id);
   }
 
+  /**
+   * The browser this browser context belongs to.
+   */
   browser(): Browser {
     return this._browser;
   }
 
+  /**
+   * Closes the browser context. All the targets that belong to the browser context
+   * will be closed.
+   *
+   * @remarks
+   * Only incognito browser contexts can be closed.
+   */
   async close(): Promise<void> {
     assert(this._id, 'Non-incognito profiles cannot be closed!');
     await this._browser._disposeContext(this._id);