docs(new): migrate JSHandle docs to TSDoc

new-docs/puppeteer.boxmodel.md

@@ -4,7 +4,6 @@
 
 ## BoxModel interface
 
-
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.elementhandle._.md

@@ -4,7 +4,7 @@
 
 ## ElementHandle.$() method
 
-The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`<!-- -->.
+Runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`<!-- -->.
 
 <b>Signature:</b>
 

new-docs/puppeteer.elementhandle.__.md

@@ -4,7 +4,7 @@
 
 ## ElementHandle.$$() method
 
-The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`<!-- -->.
+Runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`<!-- -->.
 
 <b>Signature:</b>
 

new-docs/puppeteer.elementhandle.md

@@ -30,7 +30,7 @@ const puppeteer = require('puppeteer');
 })();
 
 ```
-ElementHandle prevents DOM element from garbage collection unless the handle is [disposed](./puppeteer.jshandle.dispose.md)<!-- -->. ElementHandles are auto-disposed when their origin frame gets navigated.
+ElementHandle prevents the DOM element from being garbage-collected unless the handle is [disposed](./puppeteer.jshandle.dispose.md)<!-- -->. ElementHandles are auto-disposed when their origin frame gets navigated.
 
 ElementHandle instances can be used as arguments in [Page.$eval()](./puppeteer.page._eval.md) and [Page.evaluate()](./puppeteer.page.evaluate.md) methods.
 
@@ -40,8 +40,8 @@ The constructor for this class is marked as internal. Third-party code should no
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [$(selector)](./puppeteer.elementhandle._.md) |  | The method runs <code>element.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>. |
-|  [$$(selector)](./puppeteer.elementhandle.__.md) |  | The method runs <code>element.querySelectorAll</code> within the page. If no elements match the selector, the return value resolves to <code>[]</code>. |
+|  [$(selector)](./puppeteer.elementhandle._.md) |  | Runs <code>element.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>. |
+|  [$$(selector)](./puppeteer.elementhandle.__.md) |  | Runs <code>element.querySelectorAll</code> within the page. If no elements match the selector, the return value resolves to <code>[]</code>. |
 |  [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md) |  | This method runs <code>document.querySelectorAll</code> within the element and passes it as the first argument to <code>pageFunction</code>. If there's no element matching <code>selector</code>, the method throws an error.<!-- -->If <code>pageFunction</code> returns a Promise, then <code>frame.$$eval</code> would wait for the promise to resolve and return its value. |
 |  [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md) |  | This method runs <code>document.querySelector</code> within the element and passes it as the first argument to <code>pageFunction</code>. If there's no element matching <code>selector</code>, the method throws an error.<!-- -->If <code>pageFunction</code> returns a Promise, then <code>frame.$eval</code> would wait for the promise to resolve and return its value. |
 |  [$x(expression)](./puppeteer.elementhandle._x.md) |  | The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array. |

new-docs/puppeteer.jshandle.aselement.md

@@ -4,6 +4,8 @@
 
 ## JSHandle.asElement() method
 
+Returns either `null` or the object handle itself, if the object handle is an instance of [ElementHandle](./puppeteer.elementhandle.md)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.jshandle.dispose.md

@@ -4,7 +4,7 @@
 
 ## JSHandle.dispose() method
 
-The method stops referencing the element handle.
+Stops referencing the element handle, and resolves when the object handle is successfully disposed of.
 
 <b>Signature:</b>
 

new-docs/puppeteer.jshandle.evaluatehandle.md

@@ -25,9 +25,9 @@ Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
 
 ## Remarks
 
-The only difference between `evaluateHandle.evaluate` and `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
+The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns an in-page object (JSHandle).
 
-If the function passed to the `evaluateHandle.evaluateHandle` returns a Promise, then `evaluateHandle.evaluateHandle` would wait for the promise to resolve and return its value.
+If the function passed to `jsHandle.evaluateHandle` returns a Promise, then `evaluateHandle.evaluateHandle` waits for the promise to resolve and returns its value.
 
 See [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) for more details.
 

new-docs/puppeteer.jshandle.executioncontext.md

@@ -4,6 +4,8 @@
 
 ## JSHandle.executionContext() method
 
+Returns the execution context the handle belongs to.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.jshandle.getproperty.md

@@ -4,6 +4,8 @@
 
 ## JSHandle.getProperty() method
 
+Fetches a single property from the referenced object.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.jshandle.jsonvalue.md

@@ -17,5 +17,5 @@ Promise<{}>
 
 ## Remarks
 
-The JSON is generated by running [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer. \*\*NOTE\*\* The method will throw if the referenced object is not stringifiable.
+The JSON is generated by running [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer. \*\*NOTE\*\* The method throws if the referenced object is not stringifiable.
 

new-docs/puppeteer.jshandle.md

@@ -4,13 +4,25 @@
 
 ## JSHandle class
 
+Represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](./puppeteer.page.evaluatehandle.md) method.
 
 <b>Signature:</b>
 
 ```typescript
 export declare class JSHandle 
 ```
 
+## Example
+
+
+```js
+const windowHandle = await page.evaluateHandle(() => window);
+
+```
+JSHandle prevents the referenced JavaScript object from being garbage-collected unless the handle is [disposed](./puppeteer.jshandle.dispose.md)<!-- -->. JSHandles are auto- disposed when their origin frame gets navigated or the parent context gets destroyed.
+
+JSHandle instances can be used as arguments for [Page.$eval()](./puppeteer.page._eval.md)<!-- -->, [Page.evaluate()](./puppeteer.page.evaluate.md)<!-- -->, and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md)<!-- -->.
+
 ## Constructors
 
 |  Constructor | Modifiers | Description |
@@ -30,13 +42,13 @@ export declare class JSHandle
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [asElement()](./puppeteer.jshandle.aselement.md) |  |  |
-|  [dispose()](./puppeteer.jshandle.dispose.md) |  | The method stops referencing the element handle. |
+|  [asElement()](./puppeteer.jshandle.aselement.md) |  | Returns either <code>null</code> or the object handle itself, if the object handle is an instance of [ElementHandle](./puppeteer.elementhandle.md)<!-- -->. |
+|  [dispose()](./puppeteer.jshandle.dispose.md) |  | Stops referencing the element handle, and resolves when the object handle is successfully disposed of. |
 |  [evaluate(pageFunction, args)](./puppeteer.jshandle.evaluate.md) |  | This method passes this handle as the first argument to <code>pageFunction</code>. If <code>pageFunction</code> returns a Promise, then <code>handle.evaluate</code> would wait for the promise to resolve and return its value. |
 |  [evaluateHandle(pageFunction, args)](./puppeteer.jshandle.evaluatehandle.md) |  | This method passes this handle as the first argument to <code>pageFunction</code>. |
-|  [executionContext()](./puppeteer.jshandle.executioncontext.md) |  |  |
+|  [executionContext()](./puppeteer.jshandle.executioncontext.md) |  | Returns the execution context the handle belongs to. |
 |  [getProperties()](./puppeteer.jshandle.getproperties.md) |  | The method returns a map with property names as keys and JSHandle instances for the property values. |
-|  [getProperty(propertyName)](./puppeteer.jshandle.getproperty.md) |  |  |
+|  [getProperty(propertyName)](./puppeteer.jshandle.getproperty.md) |  | Fetches a single property from the referenced object. |
 |  [jsonValue()](./puppeteer.jshandle.jsonvalue.md) |  | Returns a JSON representation of the object. |
-|  [toString()](./puppeteer.jshandle.tostring.md) |  |  |
+|  [toString()](./puppeteer.jshandle.tostring.md) |  | Returns a string representation of the JSHandle. |
 

new-docs/puppeteer.jshandle.tostring.md

@@ -4,6 +4,8 @@
 
 ## JSHandle.toString() method
 
+Returns a string representation of the JSHandle.
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,7 @@ toString(): string;
 
 string
 
+## Remarks
+
+Useful during debugging.
+

new-docs/puppeteer.md

@@ -25,7 +25,7 @@
 |  [FrameManager](./puppeteer.framemanager.md) |  |
 |  [HTTPRequest](./puppeteer.httprequest.md) |  |
 |  [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. |
-|  [JSHandle](./puppeteer.jshandle.md) |  |
+|  [JSHandle](./puppeteer.jshandle.md) | Represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](./puppeteer.page.evaluatehandle.md) method. |
 |  [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md)<!-- -->, which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. |
 |  [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. |

src/common/JSHandle.ts

@@ -24,9 +24,6 @@ import { FrameManager, Frame } from './FrameManager';
 import { getQueryHandlerAndSelector } from './QueryHandler';
 import Protocol from '../protocol';
 
-/**
- * @public
- */
 export interface BoxModel {
   content: Array<{ x: number; y: number }>;
   padding: Array<{ x: number; y: number }>;
@@ -80,6 +77,21 @@ export function createJSHandle(
 }
 
 /**
+ * Represents an in-page JavaScript object. JSHandles can be created with the
+ * {@link Page.evaluateHandle | page.evaluateHandle} method.
+ *
+ * @example
+ * ```js
+ * const windowHandle = await page.evaluateHandle(() => window);
+ * ```
+ *
+ * JSHandle prevents the referenced JavaScript object from being garbage-collected
+ * unless the handle is {@link JSHandle.dispose | disposed}. JSHandles are auto-
+ * disposed when their origin frame gets navigated or the parent context gets destroyed.
+ *
+ * JSHandle instances can be used as arguments for {@link Page.$eval},
+ * {@link Page.evaluate}, and {@link Page.evaluateHandle}.
+ *
  * @public
  */
 export class JSHandle {
@@ -98,6 +110,8 @@ export class JSHandle {
     this._remoteObject = remoteObject;
   }
 
+  /** Returns the execution context the handle belongs to.
+   */
   executionContext(): ExecutionContext {
     return this._context;
   }
@@ -129,13 +143,13 @@ export class JSHandle {
    *
    * @remarks
    *
-   * The only difference between `evaluateHandle.evaluate` and
-   * `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle`
-   * returns in-page object (JSHandle).
+   * The only difference between `jsHandle.evaluate` and
+   * `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle`
+   * returns an in-page object (JSHandle).
    *
-   * If the function passed to the `evaluateHandle.evaluateHandle` returns a Promise,
-   * then `evaluateHandle.evaluateHandle` would wait for the promise to resolve and
-   * return its value.
+   * If the function passed to `jsHandle.evaluateHandle` returns a Promise,
+   * then `evaluateHandle.evaluateHandle` waits for the promise to resolve and
+   * returns its value.
    *
    * See {@link Page.evaluateHandle} for more details.
    */
@@ -150,6 +164,8 @@ export class JSHandle {
     );
   }
 
+  /** Fetches a single property from the referenced object.
+   */
   async getProperty(propertyName: string): Promise<JSHandle | undefined> {
     const objectHandle = await this.evaluateHandle(
       (object: HTMLElement, propertyName: string) => {
@@ -202,7 +218,7 @@ export class JSHandle {
    *
    * The JSON is generated by running {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify | JSON.stringify}
    * on the object in page and consequent {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse} in puppeteer.
-   * **NOTE** The method will throw if the referenced object is not stringifiable.
+   * **NOTE** The method throws if the referenced object is not stringifiable.
    */
   async jsonValue(): Promise<{}> {
     if (this._remoteObject.objectId) {
@@ -217,20 +233,31 @@ export class JSHandle {
     return helper.valueFromRemoteObject(this._remoteObject);
   }
 
-  /* This always returns null but children can define this and return an ElementHandle */
+  /**
+   * Returns either `null` or the object handle itself, if the object handle is
+   * an instance of {@link ElementHandle}.
+   */
   asElement(): ElementHandle | null {
+    // This always returns null, but subclasses can override this and return an
+    // ElementHandle.
     return null;
   }
 
   /**
-   * The method stops referencing the element handle.
+   * Stops referencing the element handle, and resolves when the object handle is
+   * successfully disposed of.
    */
   async dispose(): Promise<void> {
     if (this._disposed) return;
     this._disposed = true;
     await helper.releaseObject(this._client, this._remoteObject);
   }
 
+  /**
+   * Returns a string representation of the JSHandle.
+   *
+   * @remarks Useful during debugging.
+   */
   toString(): string {
     if (this._remoteObject.objectId) {
       const type = this._remoteObject.subtype || this._remoteObject.type;
@@ -260,9 +287,9 @@ export class JSHandle {
  * })();
  * ```
  *
- * ElementHandle prevents DOM element from garbage collection unless the handle is
- * {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed when their
- * origin frame gets navigated.
+ * ElementHandle prevents the DOM element from being garbage-collected unless the
+ * handle is {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed
+ * when their origin frame gets navigated.
  *
  * ElementHandle instances can be used as arguments in {@link Page.$eval} and
  * {@link Page.evaluate} methods.
@@ -711,8 +738,8 @@ export class ElementHandle extends JSHandle {
   }
 
   /**
-   * The method runs `element.querySelector` within the page. If no element matches
-   * the selector, the return value resolves to `null`.
+   * Runs `element.querySelector` within the page. If no element matches the selector,
+   * the return value resolves to `null`.
    */
   async $(selector: string): Promise<ElementHandle | null> {
     const defaultHandler = (element: Element, selector: string) =>
@@ -730,8 +757,8 @@ export class ElementHandle extends JSHandle {
   }
 
   /**
-   * The method runs `element.querySelectorAll` within the page. If no elements match
-   * the selector, the return value resolves to `[]`.
+   * Runs `element.querySelectorAll` within the page. If no elements match the selector,
+   * the return value resolves to `[]`.
    */
   async $$(selector: string): Promise<ElementHandle[]> {
     const defaultHandler = (element: Element, selector: string) =>