docs(new): add TSDoc comments to Puppeteer (#6032) (#6094)

Co-authored-by: Martin Splitt <mr.avgp@googlemail.com>

new-docs/puppeteer.executioncontext._adoptbackendnodeid.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; [ExecutionContext](./puppeteer.executioncontext.md) &gt; [\_adoptBackendNodeId](./puppeteer.executioncontext._adoptbackendnodeid.md)
-
-## ExecutionContext.\_adoptBackendNodeId() method
-
-<b>Signature:</b>
-
-```typescript
-_adoptBackendNodeId(backendNodeId: Protocol.DOM.BackendNodeId): Promise<ElementHandle>;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  backendNodeId | Protocol.DOM.BackendNodeId |  |
-
-<b>Returns:</b>
-
-Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)<!-- -->&gt;
-

new-docs/puppeteer.executioncontext._adoptelementhandle.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; [ExecutionContext](./puppeteer.executioncontext.md) &gt; [\_adoptElementHandle](./puppeteer.executioncontext._adoptelementhandle.md)
-
-## ExecutionContext.\_adoptElementHandle() method
-
-<b>Signature:</b>
-
-```typescript
-_adoptElementHandle(elementHandle: ElementHandle): Promise<ElementHandle>;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  elementHandle | [ElementHandle](./puppeteer.elementhandle.md) |  |
-
-<b>Returns:</b>
-
-Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)<!-- -->&gt;
-

new-docs/puppeteer.executioncontext._client.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; [ExecutionContext](./puppeteer.executioncontext.md) &gt; [\_client](./puppeteer.executioncontext._client.md)
-
-## ExecutionContext.\_client property
-
-<b>Signature:</b>
-
-```typescript
-_client: CDPSession;
-```

new-docs/puppeteer.executioncontext._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; [ExecutionContext](./puppeteer.executioncontext.md) &gt; [(constructor)](./puppeteer.executioncontext._constructor_.md)
-
-## ExecutionContext.(constructor)
-
-Constructs a new instance of the `ExecutionContext` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(client: CDPSession, contextPayload: Protocol.Runtime.ExecutionContextDescription, world: DOMWorld);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  client | [CDPSession](./puppeteer.cdpsession.md) |  |
-|  contextPayload | Protocol.Runtime.ExecutionContextDescription |  |
-|  world | DOMWorld |  |
-

new-docs/puppeteer.executioncontext._contextid.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; [ExecutionContext](./puppeteer.executioncontext.md) &gt; [\_contextId](./puppeteer.executioncontext._contextid.md)
-
-## ExecutionContext.\_contextId property
-
-<b>Signature:</b>
-
-```typescript
-_contextId: number;
-```

new-docs/puppeteer.executioncontext._world.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; [ExecutionContext](./puppeteer.executioncontext.md) &gt; [\_world](./puppeteer.executioncontext._world.md)
-
-## ExecutionContext.\_world property
-
-<b>Signature:</b>
-
-```typescript
-_world: DOMWorld;
-```

new-docs/puppeteer.executioncontext.evaluate.md

@@ -14,10 +14,51 @@ evaluate<ReturnType extends any>(pageFunction: Function | string, ...args: unkno
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  pageFunction | Function \| string |  |
+|  pageFunction | Function \| string | a function to be evaluated in the <code>executionContext</code> |
-|  args | unknown\[\] |  |
+|  args | unknown\[\] | argument to pass to the page function |
 
 <b>Returns:</b>
 
 Promise&lt;ReturnType&gt;
 
+A promise that resolves to the return value of the given function.
+
+## Remarks
+
+If the function passed to the `executionContext.evaluate` returns a Promise, then `executionContext.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `executionContext.evaluate` returns a non-serializable value, then `executionContext.evaluate` resolves to `undefined`<!-- -->. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`<!-- -->: `-0`<!-- -->, `NaN`<!-- -->, `Infinity`<!-- -->, `-Infinity`<!-- -->, and bigint literals.
+
+## Example 1
+
+
+```js
+const executionContext = await page.mainFrame().executionContext();
+const result = await executionContext.evaluate(() => Promise.resolve(8 * 7))* ;
+console.log(result); // prints "56"
+
+```
+
+## Example 2
+
+A string can also be passed in instead of a function.
+
+```js
+console.log(await executionContext.evaluate('1 + 2')); // prints "3"
+
+```
+
+## Example 3
+
+[JSHandle](./puppeteer.jshandle.md) instances can be passed as arguments to the `executionContext.* evaluate`<!-- -->:
+
+```js
+const oneHandle = await executionContext.evaluateHandle(() => 1);
+const twoHandle = await executionContext.evaluateHandle(() => 2);
+const result = await executionContext.evaluate(
+   (a, b) => a + b, oneHandle, * twoHandle
+);
+await oneHandle.dispose();
+await twoHandle.dispose();
+console.log(result); // prints '3'.
+
+```
+

new-docs/puppeteer.executioncontext.evaluatehandle.md

@@ -14,10 +14,49 @@ evaluateHandle(pageFunction: Function | string, ...args: unknown[]): Promise<JSH
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  pageFunction | Function \| string |  |
+|  pageFunction | Function \| string | a function to be evaluated in the <code>executionContext</code> |
-|  args | unknown\[\] |  |
+|  args | unknown\[\] | argument to pass to the page function |
 
 <b>Returns:</b>
 
 Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
 
+A promise that resolves to the return value of the given function as an in-page object (a [JSHandle](./puppeteer.jshandle.md)<!-- -->).
+
+## Remarks
+
+The only difference between `executionContext.evaluate` and `executionContext.evaluateHandle` is that `executionContext.evaluateHandle` returns an in-page object (a [JSHandle](./puppeteer.jshandle.md)<!-- -->). If the function passed to the `executionContext.evaluateHandle` returns a Promise, then `executionContext.evaluateHandle` would wait for the promise to resolve and return its value.
+
+## Example 1
+
+
+```js
+const context = await page.mainFrame().executionContext();
+const aHandle = await context.evaluateHandle(() => Promise.resolve(self));
+aHandle; // Handle for the global object.
+
+```
+
+## Example 2
+
+A string can also be passed in instead of a function.
+
+```js
+// Handle for the '3' * object.
+const aHandle = await context.evaluateHandle('1 + 2');
+
+```
+
+## Example 3
+
+JSHandle instances can be passed as arguments to the `executionContext.* evaluateHandle`<!-- -->:
+
+```js
+const aHandle = await context.evaluateHandle(() => document.body);
+const resultHandle = await context.evaluateHandle(body => body.innerHTML, * aHandle);
+console.log(await resultHandle.jsonValue()); // prints body's innerHTML
+await aHandle.dispose();
+await resultHandle.dispose();
+
+```
+

new-docs/puppeteer.executioncontext.frame.md

@@ -13,3 +13,9 @@ frame(): Frame | null;
 
 [Frame](./puppeteer.frame.md) \| null
 
+The frame associated with this execution context.
+
+## Remarks
+
+Not every execution context is associated with a frame. For example, workers and extensions have execution contexts that are not associated with frames.
+

new-docs/puppeteer.executioncontext.md

@@ -4,34 +4,26 @@
 
 ## ExecutionContext class
 
+This class represents a context for JavaScript execution. A \[Page\] might have many execution contexts: - each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has "default" execution context that is always created after frame is attached to DOM. This context is returned by the  method. - [Extension](https://developer.chrome.com/extensions)<!-- -->'s content scripts create additional execution contexts.
+
+Besides pages, execution contexts can be found in [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class ExecutionContext 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | 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 `ExecutionContext` class.
-|  --- | --- | --- |
-|  [(constructor)(client, contextPayload, world)](./puppeteer.executioncontext._constructor_.md) |  | Constructs a new instance of the <code>ExecutionContext</code> class |
-
-## Properties
-
-|  Property | Modifiers | Type | Description |
-|  --- | --- | --- | --- |
-|  [\_client](./puppeteer.executioncontext._client.md) |  | [CDPSession](./puppeteer.cdpsession.md) |  |
-|  [\_contextId](./puppeteer.executioncontext._contextid.md) |  | number |  |
-|  [\_world](./puppeteer.executioncontext._world.md) |  | DOMWorld |  |
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [\_adoptBackendNodeId(backendNodeId)](./puppeteer.executioncontext._adoptbackendnodeid.md) |  |  |
-|  [\_adoptElementHandle(elementHandle)](./puppeteer.executioncontext._adoptelementhandle.md) |  |  |
 |  [evaluate(pageFunction, args)](./puppeteer.executioncontext.evaluate.md) |  |  |
 |  [evaluateHandle(pageFunction, args)](./puppeteer.executioncontext.evaluatehandle.md) |  |  |
 |  [frame()](./puppeteer.executioncontext.frame.md) |  |  |
-|  [queryObjects(prototypeHandle)](./puppeteer.executioncontext.queryobjects.md) |  |  |
+|  [queryObjects(prototypeHandle)](./puppeteer.executioncontext.queryobjects.md) |  | This method iterates the JavaScript heap and finds all the objects with the given prototype. |
 

new-docs/puppeteer.executioncontext.queryobjects.md

@@ -4,6 +4,8 @@
 
 ## ExecutionContext.queryObjects() method
 
+This method iterates the JavaScript heap and finds all the objects with the given prototype.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,31 @@ queryObjects(prototypeHandle: JSHandle): Promise<JSHandle>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  prototypeHandle | [JSHandle](./puppeteer.jshandle.md) |  |
+|  prototypeHandle | [JSHandle](./puppeteer.jshandle.md) | a handle to the object prototype |
 
 <b>Returns:</b>
 
 Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
 
+A handle to an array of objects with the given prototype.
+
+## Remarks
+
+
+## Example
+
+
+```js
+// Create a Map object
+await page.evaluate(() => window.map = new Map());
+// Get a handle to the Map object prototype
+const mapPrototype = await page.evaluateHandle(() => Map.prototype);
+// Query all map instances into an array
+const mapInstances = await page.queryObjects(mapPrototype);
+// Count amount of map objects in heap
+const count = await page.evaluate(maps => maps.length, mapInstances);
+await mapInstances.dispose();
+await mapPrototype.dispose();
+
+```
+

new-docs/puppeteer.md

@@ -19,7 +19,7 @@
 |  [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the <code>dialog</code> event. |
 |  [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. |
 |  [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. |
-|  [ExecutionContext](./puppeteer.executioncontext.md) |  |
+|  [ExecutionContext](./puppeteer.executioncontext.md) | This class represents a context for JavaScript execution. A \[Page\] might have many execution contexts: - each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has "default" execution context that is always created after frame is attached to DOM. This context is returned by the  method. - [Extension](https://developer.chrome.com/extensions)<!-- -->'s content scripts create additional execution contexts.<!-- -->Besides pages, execution contexts can be found in [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)<!-- -->. |
 |  [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. |
 |  [Frame](./puppeteer.frame.md) |  |
 |  [FrameManager](./puppeteer.framemanager.md) |  |

src/common/ExecutionContext.ts

@@ -25,11 +25,37 @@ import Protocol from '../protocol';
 export const EVALUATION_SCRIPT_URL = '__puppeteer_evaluation_script__';
 const SOURCE_URL_REGEX = /^[\040\t]*\/\/[@#] sourceURL=\s*(\S*?)\s*$/m;
 
+/**
+ * This class represents a context for JavaScript execution. A [Page] might have
+ * many execution contexts:
+ * - each
+ *   {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe |
+ *   frame } has "default" execution context that is always created after frame is
+ *   attached to DOM. This context is returned by the
+ *   {@link frame.executionContext()} method.
+ * - {@link https://developer.chrome.com/extensions | Extension}'s content scripts
+ *   create additional execution contexts.
+ *
+ * Besides pages, execution contexts can be found in
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API |
+ * workers }.
+ *
+ * @public
+ */
 export class ExecutionContext {
+  /**
+   * @internal
+   */
   _client: CDPSession;
+  /**
+   * @internal
+   */
   _world: DOMWorld;
-  _contextId: number;
+  private _contextId: number;
 
+  /**
+   * @internal
+   */
   constructor(
     client: CDPSession,
     contextPayload: Protocol.Runtime.ExecutionContextDescription,
@@ -40,10 +66,62 @@ export class ExecutionContext {
     this._contextId = contextPayload.id;
   }
 
+  /**
+   * @remarks
+   *
+   * Not every execution context is associated with a frame. For
+   * example, workers and extensions have execution contexts that are not
+   * associated with frames.
+   *
+   * @returns The frame associated with this execution context.
+   */
   frame(): Frame | null {
     return this._world ? this._world.frame() : null;
   }
 
+  /**
+   * @remarks
+   * If the function passed to the `executionContext.evaluate` returns a
+   * Promise, then `executionContext.evaluate` would wait for the promise to
+   * resolve and return its value. If the function passed to the
+   * `executionContext.evaluate` returns a non-serializable value, then
+   * `executionContext.evaluate` resolves to `undefined`. DevTools Protocol also
+   * supports transferring some additional values that are not serializable by
+   * `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
+   *
+   *
+   * @example
+   * ```js
+   * const executionContext = await page.mainFrame().executionContext();
+   * const result = await executionContext.evaluate(() => Promise.resolve(8 * 7))* ;
+   * console.log(result); // prints "56"
+   * ```
+   *
+   * @example
+   * A string can also be passed in instead of a function.
+   *
+   * ```js
+   * console.log(await executionContext.evaluate('1 + 2')); // prints "3"
+   * ```
+   *
+   * @example
+   * {@link JSHandle} instances can be passed as arguments to the
+   * `executionContext.* evaluate`:
+   * ```js
+   * const oneHandle = await executionContext.evaluateHandle(() => 1);
+   * const twoHandle = await executionContext.evaluateHandle(() => 2);
+   * const result = await executionContext.evaluate(
+   *    (a, b) => a + b, oneHandle, * twoHandle
+   * );
+   * await oneHandle.dispose();
+   * await twoHandle.dispose();
+   * console.log(result); // prints '3'.
+   * ```
+   * @param pageFunction a function to be evaluated in the `executionContext`
+   * @param args argument to pass to the page function
+   *
+   * @returns A promise that resolves to the return value of the given function.
+   */
   async evaluate<ReturnType extends any>(
     pageFunction: Function | string,
     ...args: unknown[]
@@ -55,6 +133,48 @@ export class ExecutionContext {
     );
   }
 
+  /**
+   * @remarks
+   * The only difference between `executionContext.evaluate` and
+   * `executionContext.evaluateHandle` is that `executionContext.evaluateHandle`
+   * returns an in-page object (a {@link JSHandle}).
+   * If the function passed to the `executionContext.evaluateHandle` returns a
+   * Promise, then `executionContext.evaluateHandle` would wait for the
+   * promise to resolve and return its value.
+   *
+   * @example
+   * ```js
+   * const context = await page.mainFrame().executionContext();
+   * const aHandle = await context.evaluateHandle(() => Promise.resolve(self));
+   * aHandle; // Handle for the global object.
+   * ```
+   *
+   * @example
+   * A string can also be passed in instead of a function.
+   *
+   * ```js
+   * // Handle for the '3' * object.
+   * const aHandle = await context.evaluateHandle('1 + 2');
+   * ```
+   *
+   * @example
+   * JSHandle instances can be passed as arguments
+   * to the `executionContext.* evaluateHandle`:
+   *
+   * ```js
+   * const aHandle = await context.evaluateHandle(() => document.body);
+   * const resultHandle = await context.evaluateHandle(body => body.innerHTML, * aHandle);
+   * console.log(await resultHandle.jsonValue()); // prints body's innerHTML
+   * await aHandle.dispose();
+   * await resultHandle.dispose();
+   * ```
+   *
+   * @param pageFunction a function to be evaluated in the `executionContext`
+   * @param args argument to pass to the page function
+   *
+   * @returns A promise that resolves to the return value of the given function
+   * as an in-page object (a {@link JSHandle}).
+   */
   async evaluateHandle(
     pageFunction: Function | string,
     ...args: unknown[]
@@ -197,6 +317,28 @@ export class ExecutionContext {
     }
   }
 
+  /**
+   * This method iterates the JavaScript heap and finds all the objects with the
+   * given prototype.
+   * @remarks
+   * @example
+   * ```js
+   * // Create a Map object
+   * await page.evaluate(() => window.map = new Map());
+   * // Get a handle to the Map object prototype
+   * const mapPrototype = await page.evaluateHandle(() => Map.prototype);
+   * // Query all map instances into an array
+   * const mapInstances = await page.queryObjects(mapPrototype);
+   * // Count amount of map objects in heap
+   * const count = await page.evaluate(maps => maps.length, mapInstances);
+   * await mapInstances.dispose();
+   * await mapPrototype.dispose();
+   * ```
+   *
+   * @param prototypeHandle a handle to the object prototype
+   *
+   * @returns A handle to an array of objects with the given prototype.
+   */
   async queryObjects(prototypeHandle: JSHandle): Promise<JSHandle> {
     assert(!prototypeHandle._disposed, 'Prototype JSHandle is disposed!');
     assert(
@@ -209,6 +351,9 @@ export class ExecutionContext {
     return createJSHandle(this, response.objects);
   }
 
+  /**
+   * @internal
+   */
   async _adoptBackendNodeId(
     backendNodeId: Protocol.DOM.BackendNodeId
   ): Promise<ElementHandle> {
@@ -219,6 +364,9 @@ export class ExecutionContext {
     return createJSHandle(this, object) as ElementHandle;
   }
 
+  /**
+   * @internal
+   */
   async _adoptElementHandle(
     elementHandle: ElementHandle
   ): Promise<ElementHandle> {