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

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

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 |  |
-|  args | unknown\[\] |  |
+|  pageFunction | Function \| string | a function to be evaluated in the <code>executionContext</code> |
+|  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 |  |
-|  args | unknown\[\] |  |
+|  pageFunction | Function \| string | a function to be evaluated in the <code>executionContext</code> |
+|  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
-
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(client, contextPayload, world)](./puppeteer.executioncontext._constructor_.md) |  | Constructs a new instance of the <code>ExecutionContext</code> class |
-
-## Properties
+## Remarks
 
-|  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 |  |
+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.
 
 ## 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) |  |