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

puppeteer · Jun 23, 2020 · 4659ee8 · 4659ee8
1 parent ccae546
commit 4659ee8
Show file tree

Hide file tree

Showing 16 changed files with 270 additions and 157 deletions.
diff --git a/new-docs/puppeteer.browsercontext._browser.md b/new-docs/puppeteer.browsercontext._browser.md
diff --git a/new-docs/puppeteer.browsercontext._connection.md b/new-docs/puppeteer.browsercontext._connection.md
diff --git a/new-docs/puppeteer.browsercontext._constructor_.md b/new-docs/puppeteer.browsercontext._constructor_.md
diff --git a/new-docs/puppeteer.browsercontext._id.md b/new-docs/puppeteer.browsercontext._id.md
diff --git a/new-docs/puppeteer.browsercontext.browser.md b/new-docs/puppeteer.browsercontext.browser.md
@@ -4,6 +4,8 @@
 
 ## BrowserContext.browser() method
 
+The browser this browser context belongs to.
+
 <b>Signature:</b>
 
 ```typescript

diff --git a/new-docs/puppeteer.browsercontext.clearpermissionoverrides.md b/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();
+
+```
+
diff --git a/new-docs/puppeteer.browsercontext.close.md b/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.
+
diff --git a/new-docs/puppeteer.browsercontext.isincognito.md b/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.
+
diff --git a/new-docs/puppeteer.browsercontext.md b/new-docs/puppeteer.browsercontext.md
@@ -4,38 +4,49 @@
 
 ## 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
 export declare class BrowserContext extends EventEmitter 
 ```
 <b>Extends:</b> [EventEmitter](./puppeteer.eventemitter.md)
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(connection, browser, contextId)](./puppeteer.browsercontext._constructor_.md) |  | Constructs a new instance of the <code>BrowserContext</code> class |
+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 [Browser.createIncognitoBrowserContext](./puppeteer.browser.createincognitobrowsercontext.md) method. "Incognito" browser contexts don't write any browsing data to disk.
+
+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.
 
-## Properties
+## Example
 
-|  Property | Modifiers | Type | Description |
-|  --- | --- | --- | --- |
-|  [\_browser](./puppeteer.browsercontext._browser.md) |  | [Browser](./puppeteer.browser.md) |  |
-|  [\_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) |  |  |
-|  [clearPermissionOverrides()](./puppeteer.browsercontext.clearpermissionoverrides.md) |  |  |
-|  [close()](./puppeteer.browsercontext.close.md) |  |  |
-|  [isIncognito()](./puppeteer.browsercontext.isincognito.md) |  |  |
-|  [newPage()](./puppeteer.browsercontext.newpage.md) |  |  |
+|  [browser()](./puppeteer.browsercontext.browser.md) |  | The browser this browser context belongs to. |
+|  [clearPermissionOverrides()](./puppeteer.browsercontext.clearpermissionoverrides.md) |  | Clears all permission overrides for the browser context. |
+|  [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) |  | Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context. |
+|  [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) |  |  |
-|  [targets()](./puppeteer.browsercontext.targets.md) |  |  |
-|  [waitForTarget(predicate, options)](./puppeteer.browsercontext.waitfortarget.md) |  |  |
+|  [pages()](./puppeteer.browsercontext.pages.md) |  | An array of all pages inside the browser context. |
+|  [targets()](./puppeteer.browsercontext.targets.md) |  | An array of all active targets inside the browser context. |
+|  [waitForTarget(predicate, options)](./puppeteer.browsercontext.waitfortarget.md) |  | This searches for a target in this specific browser context. |
 
diff --git a/new-docs/puppeteer.browsercontext.newpage.md b/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

diff --git a/new-docs/puppeteer.browsercontext.overridepermissions.md b/new-docs/puppeteer.browsercontext.overridepermissions.md
@@ -14,10 +14,19 @@ overridePermissions(origin: string, permissions: Protocol.Browser.PermissionType
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  origin | string |  |
-|  permissions | Protocol.Browser.PermissionType\[\] |  |
+|  origin | string | The origin to grant permissions to, e.g. "https://example.com". |
+|  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']);
+
+```
+
diff --git a/new-docs/puppeteer.browsercontext.pages.md b/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)<!-- -->.
+
diff --git a/new-docs/puppeteer.browsercontext.targets.md b/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

diff --git a/new-docs/puppeteer.browsercontext.waitfortarget.md b/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 |  |
-|  options | { timeout?: number; } |  |
+|  predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; boolean | A function to be run for every target |
+|  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/');
+
+```
+