chore(docs): document Frame class (#6188)

* chore: document Frame class
puppeteer · Jul 9, 2020 · 24cb6a2 · 24cb6a2
1 parent b9667f9
commit 24cb6a2
Show file tree

Hide file tree

Showing 53 changed files with 1,200 additions and 183 deletions.
diff --git a/new-docs/puppeteer.frame._.md b/new-docs/puppeteer.frame._.md
@@ -4,6 +4,8 @@
 
 ## Frame.$() method
 
+This method queries the frame for the given selector.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,11 @@ $(selector: string): Promise<ElementHandle | null>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
+|  selector | string | a selector to query for. |
 
 <b>Returns:</b>
 
 Promise&lt;[ElementHandle](./puppeteer.elementhandle.md) \| null&gt;
 
+A promise which resolves to an `ElementHandle` pointing at the element, or `null` if it was not found.
+
diff --git a/new-docs/puppeteer.frame.__.md b/new-docs/puppeteer.frame.__.md
@@ -4,6 +4,8 @@
 
 ## Frame.$$() method
 
+This runs `document.querySelectorAll` in the frame and returns the result.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,11 @@ $$(selector: string): Promise<ElementHandle[]>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
+|  selector | string | a selector to search for |
 
 <b>Returns:</b>
 
 Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)<!-- -->\[\]&gt;
 
+An array of element handles pointing to the found frame elements.
+
diff --git a/new-docs/puppeteer.frame.__eval.md b/new-docs/puppeteer.frame.__eval.md
@@ -14,11 +14,25 @@ $$eval<ReturnType>(selector: string, pageFunction: (elements: Element[], ...args
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
-|  pageFunction | (elements: Element\[\], ...args: unknown\[\]) =&gt; ReturnType \| Promise&lt;ReturnType&gt; |  |
-|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] |  |
+|  selector | string | the selector to query for |
+|  pageFunction | (elements: Element\[\], ...args: unknown\[\]) =&gt; ReturnType \| Promise&lt;ReturnType&gt; | the function to be evaluated in the frame's context |
+|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | additional arguments to pass to <code>pageFuncton</code> |
 
 <b>Returns:</b>
 
 Promise&lt;[WrapElementHandle](./puppeteer.wrapelementhandle.md)<!-- -->&lt;ReturnType&gt;&gt;
 
+## Remarks
+
+This method runs `Array.from(document.querySelectorAll(selector))` within the frame and passes it as the first argument to `pageFunction`<!-- -->.
+
+If `pageFunction` returns a Promise, then `frame.$$eval` would wait for the promise to resolve and return its value.
+
+## Example
+
+
+```js
+const divsCounts = await frame.$$eval('div', divs => divs.length);
+
+```
+
diff --git a/new-docs/puppeteer.frame._detach.md b/new-docs/puppeteer.frame._detach.md
diff --git a/new-docs/puppeteer.frame._eval.md b/new-docs/puppeteer.frame._eval.md
@@ -14,11 +14,25 @@ $eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: un
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
-|  pageFunction | (element: Element, ...args: unknown\[\]) =&gt; ReturnType \| Promise&lt;ReturnType&gt; |  |
-|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] |  |
+|  selector | string | the selector to query for |
+|  pageFunction | (element: Element, ...args: unknown\[\]) =&gt; ReturnType \| Promise&lt;ReturnType&gt; | the function to be evaluated in the frame's context |
+|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | additional arguments to pass to <code>pageFuncton</code> |
 
 <b>Returns:</b>
 
 Promise&lt;[WrapElementHandle](./puppeteer.wrapelementhandle.md)<!-- -->&lt;ReturnType&gt;&gt;
 
+## Remarks
+
+This method runs `document.querySelector` within the frame and passes it as the first argument to `pageFunction`<!-- -->.
+
+If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise to resolve and return its value.
+
+## Example
+
+
+```js
+const searchValue = await frame.$eval('#search', el => el.value);
+
+```
+
diff --git a/new-docs/puppeteer.frame._navigated.md b/new-docs/puppeteer.frame._navigated.md
diff --git a/new-docs/puppeteer.frame._navigatedwithindocument.md b/new-docs/puppeteer.frame._navigatedwithindocument.md
diff --git a/new-docs/puppeteer.frame._onlifecycleevent.md b/new-docs/puppeteer.frame._onlifecycleevent.md
diff --git a/new-docs/puppeteer.frame._onloadingstopped.md b/new-docs/puppeteer.frame._onloadingstopped.md
diff --git a/new-docs/puppeteer.frame._x.md b/new-docs/puppeteer.frame._x.md
@@ -4,6 +4,8 @@
 
 ## Frame.$x() method
 
+This method evaluates the given XPath expression and returns the results.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,7 +16,7 @@ $x(expression: string): Promise<ElementHandle[]>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  expression | string |  |
+|  expression | string | the XPath expression to evaluate. |
 
 <b>Returns:</b>
 

diff --git a/new-docs/puppeteer.frame.addscripttag.md b/new-docs/puppeteer.frame.addscripttag.md
@@ -4,24 +4,23 @@
 
 ## Frame.addScriptTag() method
 
+Adds a `<script>` tag into the page with the desired url or content.
+
 <b>Signature:</b>
 
 ```typescript
-addScriptTag(options: {
-        url?: string;
-        path?: string;
-        content?: string;
-        type?: string;
-    }): Promise<ElementHandle>;
+addScriptTag(options: FrameAddScriptTagOptions): Promise<ElementHandle>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { url?: string; path?: string; content?: string; type?: string; } |  |
+|  options | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md) | configure the script to add to the page. |
 
 <b>Returns:</b>
 
 Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)<!-- -->&gt;
 
+a promise that resolves to the added tag when the script's `onload` event fires or when the script content was injected into the frame.
+
diff --git a/new-docs/puppeteer.frame.addstyletag.md b/new-docs/puppeteer.frame.addstyletag.md
@@ -4,23 +4,23 @@
 
 ## Frame.addStyleTag() method
 
+Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content.
+
 <b>Signature:</b>
 
 ```typescript
-addStyleTag(options: {
-        url?: string;
-        path?: string;
-        content?: string;
-    }): Promise<ElementHandle>;
+addStyleTag(options: FrameAddStyleTagOptions): Promise<ElementHandle>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { url?: string; path?: string; content?: string; } |  |
+|  options | [FrameAddStyleTagOptions](./puppeteer.frameaddstyletagoptions.md) | configure the CSS to add to the page. |
 
 <b>Returns:</b>
 
 Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)<!-- -->&gt;
 
+a promise that resolves to the added tag when the stylesheets's `onload` event fires or when the CSS content was injected into the frame.
+
diff --git a/new-docs/puppeteer.frame.childframes.md b/new-docs/puppeteer.frame.childframes.md
@@ -13,3 +13,5 @@ childFrames(): Frame[];
 
 [Frame](./puppeteer.frame.md)<!-- -->\[\]
 
+an array of child frames.
+
diff --git a/new-docs/puppeteer.frame.click.md b/new-docs/puppeteer.frame.click.md
@@ -4,6 +4,8 @@
 
 ## Frame.click() method
 
+This method clicks the first element found that matches `selector`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -18,10 +20,24 @@ click(selector: string, options?: {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
+|  selector | string | the selector to search for to click. If there are multiple elements, the first will be clicked. |
 |  options | { delay?: number; button?: [MouseButton](./puppeteer.mousebutton.md)<!-- -->; clickCount?: number; } |  |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+This method scrolls the element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to click in the center of the element. If there's no element matching `selector`<!-- -->, the method throws an error.
+
+Bear in mind that if `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
+
+```javascript
+const [response] = await Promise.all([
+  page.waitForNavigation(waitOptions),
+  frame.click(selector, clickOptions),
+]);
+
+```
+
diff --git a/new-docs/puppeteer.frame.content.md b/new-docs/puppeteer.frame.content.md
@@ -13,3 +13,5 @@ content(): Promise<string>;
 
 Promise&lt;string&gt;
 
+the full HTML contents of the frame, including the doctype.
+
diff --git a/new-docs/puppeteer.frame.evaluate.md b/new-docs/puppeteer.frame.evaluate.md
@@ -14,10 +14,14 @@ evaluate<ReturnType extends any>(pageFunction: Function | string, ...args: unkno
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  pageFunction | Function \| string |  |
-|  args | unknown\[\] |  |
+|  pageFunction | Function \| string | a function that is run within the frame |
+|  args | unknown\[\] | arguments to be passed to the pageFunction |
 
 <b>Returns:</b>
 
 Promise&lt;ReturnType&gt;
 
+## Remarks
+
+This method behaves identically to [Page.evaluate()](./puppeteer.page.evaluate.md) except it's run within the context of the `frame`<!-- -->, rather than the entire page.
+
diff --git a/new-docs/puppeteer.frame.evaluatehandle.md b/new-docs/puppeteer.frame.evaluatehandle.md
@@ -14,10 +14,16 @@ evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHa
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  pageFunction | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) |  |
-|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] |  |
+|  pageFunction | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | a function that is run within the frame |
+|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | arguments to be passed to the pageFunction |
 
 <b>Returns:</b>
 
 Promise&lt;HandlerType&gt;
 
+## Remarks
+
+The only difference between [Frame.evaluate()](./puppeteer.frame.evaluate.md) and `frame.evaluateHandle` is that `evaluateHandle` will return the value wrapped in an in-page object.
+
+This method behaves identically to [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) except it's run within the context of the `frame`<!-- -->, rather than the entire page.
+
diff --git a/new-docs/puppeteer.frame.executioncontext.md b/new-docs/puppeteer.frame.executioncontext.md
@@ -13,3 +13,5 @@ executionContext(): Promise<ExecutionContext>;
 
 Promise&lt;[ExecutionContext](./puppeteer.executioncontext.md)<!-- -->&gt;
 
+a promise that resolves to the frame's default execution context.
+
diff --git a/new-docs/puppeteer.frame.focus.md b/new-docs/puppeteer.frame.focus.md
@@ -4,6 +4,8 @@
 
 ## Frame.focus() method
 
+This method fetches an element with `selector` and focuses it.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,13 @@ focus(selector: string): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
+|  selector | string | the selector for the element to focus. If there are multiple elements, the first will be focused. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+If there's no element matching `selector`<!-- -->, the method throws an error.
+