Update the documentation.

new-docs/puppeteer.elementhandle._eval.md

@@ -11,20 +11,20 @@ If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promi
 <b>Signature:</b>
 
 ```typescript
-$eval<ReturnType extends any>(selector: string, pageFunction: EvaluateFn | string, ...args: SerializableOrJSHandle[]): Promise<ReturnType>;
+$eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  selector | string |  |
-|  pageFunction | [EvaluateFn](./puppeteer.evaluatefn.md) \| string |  |
+|  pageFunction | (element: Element, ...args: unknown\[\]) =&gt; ReturnType \| Promise&lt;ReturnType&gt; |  |
 |  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] |  |
 
 <b>Returns:</b>
 
-Promise&lt;ReturnType&gt;
+Promise&lt;[WrapElementHandle](./puppeteer.wrapelementhandle.md)<!-- -->&lt;ReturnType&gt;&gt;
 
 ## Example
 

new-docs/puppeteer.elementhandle.aselement.md

@@ -7,9 +7,9 @@
 <b>Signature:</b>
 
 ```typescript
-asElement(): ElementHandle | null;
+asElement(): ElementHandle<ElementType> | null;
 ```
 <b>Returns:</b>
 
-[ElementHandle](./puppeteer.elementhandle.md) \| null
+[ElementHandle](./puppeteer.elementhandle.md)<!-- -->&lt;ElementType&gt; \| null
 

new-docs/puppeteer.elementhandle.md

@@ -9,7 +9,7 @@ ElementHandle represents an in-page DOM element.
 <b>Signature:</b>
 
 ```typescript
-export declare class ElementHandle extends JSHandle 
+export declare class ElementHandle<ElementType extends Element = Element> extends JSHandle 
 ```
 <b>Extends:</b> [JSHandle](./puppeteer.jshandle.md)
 
@@ -34,6 +34,8 @@ ElementHandle prevents the DOM element from being garbage-collected unless the h
 
 ElementHandle instances can be used as arguments in [Page.$eval()](./puppeteer.page._eval.md) and [Page.evaluate()](./puppeteer.page.evaluate.md) methods.
 
+If you're using TypeScript, ElementHandle takes a generic argument that denotes the type of element the handle is holding within. For example, if you have a handle to a `<select>` element, you can type it as `ElementHandle<HTMLSelectElement>` and you get some nicer type checks.
+
 The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ElementHandle` class.
 
 ## Methods

new-docs/puppeteer.frame._eval.md

@@ -7,18 +7,18 @@
 <b>Signature:</b>
 
 ```typescript
-$eval<ReturnType extends any>(selector: string, pageFunction: EvaluateFn | string, ...args: SerializableOrJSHandle[]): Promise<ReturnType>;
+$eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  selector | string |  |
-|  pageFunction | [EvaluateFn](./puppeteer.evaluatefn.md) \| string |  |
+|  pageFunction | (element: Element, ...args: unknown\[\]) =&gt; ReturnType \| Promise&lt;ReturnType&gt; |  |
 |  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] |  |
 
 <b>Returns:</b>
 
-Promise&lt;ReturnType&gt;
+Promise&lt;[WrapElementHandle](./puppeteer.wrapelementhandle.md)<!-- -->&lt;ReturnType&gt;&gt;
 

new-docs/puppeteer.jshandle.evaluatehandle.md

@@ -9,7 +9,7 @@ This method passes this handle as the first argument to `pageFunction`<!-- -->.
 <b>Signature:</b>
 
 ```typescript
-evaluateHandle<HandleType extends JSHandle | ElementHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandleType>;
+evaluateHandle<HandleType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandleType>;
 ```
 
 ## Parameters

new-docs/puppeteer.md

@@ -89,4 +89,6 @@
 |  [PuppeteerErrors](./puppeteer.puppeteererrors.md) |  |
 |  [Serializable](./puppeteer.serializable.md) |  |
 |  [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md) |  |
+|  [UnwrapElementHandle](./puppeteer.unwrapelementhandle.md) | Unwraps a DOM element out of an ElementHandle instance |
+|  [WrapElementHandle](./puppeteer.wrapelementhandle.md) | Wraps a DOM element into an ElementHandle instance |
 

new-docs/puppeteer.page._eval.md

@@ -4,21 +4,65 @@
 
 ## Page.$eval() method
 
+This method runs `document.querySelector` within the page and passes the result as the first argument to the `pageFunction`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
-$eval<ReturnType extends any>(selector: string, pageFunction: EvaluateFn | string, ...args: SerializableOrJSHandle[]): Promise<ReturnType>;
+$eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
-|  pageFunction | [EvaluateFn](./puppeteer.evaluatefn.md) \| string |  |
-|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] |  |
+|  selector | string | the [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query for |
+|  pageFunction | (element: Element, ...args: unknown\[\]) =&gt; ReturnType \| Promise&lt;ReturnType&gt; | the function to be evaluated in the page context. Will be passed the result of <code>document.querySelector(selector)</code> as its first argument. |
+|  args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)<!-- -->\[\] | any additional arguments to pass through to <code>pageFunction</code>. |
 
 <b>Returns:</b>
 
-Promise&lt;ReturnType&gt;
+Promise&lt;[WrapElementHandle](./puppeteer.wrapelementhandle.md)<!-- -->&lt;ReturnType&gt;&gt;
+
+The result of calling `pageFunction`<!-- -->. If it returns an element it is wrapped in an [ElementHandle](./puppeteer.elementhandle.md)<!-- -->, else the raw value itself is returned.
+
+## Remarks
+
+If no element is found matching `selector`<!-- -->, the method will throw an error.
+
+If `pageFunction` returns a promise `$eval` will wait for the promise to resolve and then return its value.
+
+## Example 1
+
+
+```
+const searchValue = await page.$eval('#search', el => el.value);
+const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
+const html = await page.$eval('.main-container', el => el.outerHTML);
+
+```
+If you are using TypeScript, you may have to provide an explicit type to the first argument of the `pageFunction`<!-- -->. By default it is typed as `Element`<!-- -->, but you may need to provide a more specific sub-type:
+
+## Example 2
+
+
+```
+// if you don't provide HTMLInputElement here, TS will error
+// as `value` is not on `Element`
+const searchValue = await page.$eval('#search', (el: HTMLInputElement) => el.value);
+
+```
+The compiler should be able to infer the return type from the `pageFunction` you provide. If it is unable to, you can use the generic type to tell the compiler what return type you expect from `$eval`<!-- -->:
+
+## Example 3
+
+
+```
+// The compiler can infer the return type in this case, but if it can't
+// or if you want to be more explicit, provide it as the generic type.
+const searchValue = await page.$eval<string>(
+ '#search', (el: HTMLInputElement) => el.value
+);
+
+```
 

new-docs/puppeteer.page.md

@@ -73,7 +73,7 @@ page.off('request', logRequest);
 |  [$(selector)](./puppeteer.page._.md) |  | Runs <code>document.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>. |
 |  [$$(selector)](./puppeteer.page.__.md) |  |  |
 |  [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) |  |  |
-|  [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) |  |  |
+|  [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) |  | This method runs <code>document.querySelector</code> within the page and passes the result as the first argument to the <code>pageFunction</code>. |
 |  [$x(expression)](./puppeteer.page._x.md) |  |  |
 |  [addScriptTag(options)](./puppeteer.page.addscripttag.md) |  |  |
 |  [addStyleTag(options)](./puppeteer.page.addstyletag.md) |  |  |

new-docs/puppeteer.unwrapelementhandle.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [UnwrapElementHandle](./puppeteer.unwrapelementhandle.md)
+
+## UnwrapElementHandle type
+
+Unwraps a DOM element out of an ElementHandle instance
+
+<b>Signature:</b>
+
+```typescript
+export declare type UnwrapElementHandle<X> = X extends ElementHandle<infer E> ? E : X;
+```

new-docs/puppeteer.wrapelementhandle.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WrapElementHandle](./puppeteer.wrapelementhandle.md)
+
+## WrapElementHandle type
+
+Wraps a DOM element into an ElementHandle instance
+
+<b>Signature:</b>
+
+```typescript
+export declare type WrapElementHandle<X> = X extends Element ? ElementHandle<X> : X;
+```