feat(new-docs): add tsdoc comments to WebWorker (#6029)

* feat(new-docs): add TSDoc comments to `WebWorker`

Co-authored-by: martinsplitt <martin@geekonaut.de>

new-docs/puppeteer.md

@@ -35,7 +35,7 @@
 |  [TimeoutError](./puppeteer.timeouterror.md) |  |
 |  [Touchscreen](./puppeteer.touchscreen.md) |  |
 |  [Tracing](./puppeteer.tracing.md) |  |
-|  [WebWorker](./puppeteer.webworker.md) |  |
+|  [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)<!-- -->. |
 
 ## Enumerations
 

new-docs/puppeteer.webworker.evaluate.md

@@ -4,6 +4,8 @@
 
 ## WebWorker.evaluate() method
 
+If the function passed to the `worker.evaluate` returns a Promise, then `worker.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `worker.evaluate` returns a non-serializable value, then `worker.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. Shortcut for `await worker.executionContext()).evaluate(pageFunction, ...args)`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,10 +16,12 @@ evaluate<ReturnType extends any>(pageFunction: Function | string, ...args: any[]
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  pageFunction | Function \| string |  |
-|  args | any\[\] |  |
+|  pageFunction | Function \| string | Function to be evaluated in the worker context. |
+|  args | any\[\] | Arguments to pass to <code>pageFunction</code>. |
 
 <b>Returns:</b>
 
 Promise&lt;ReturnType&gt;
 
+Promise which resolves to the return value of `pageFunction`<!-- -->.
+

new-docs/puppeteer.webworker.evaluatehandle.md

@@ -4,6 +4,8 @@
 
 ## WebWorker.evaluateHandle() method
 
+The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns in-page object (JSHandle). If the function passed to the `worker.evaluateHandle` returns a \[Promise\], then `worker.evaluateHandle` would wait for the promise to resolve and return its value. Shortcut for \[(await worker.executionContext()).evaluateHandle(pageFunction, ...args)\](\#executioncontextevaluatehandlepagefunction-args).
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,10 +16,12 @@ evaluateHandle(pageFunction: Function | string, ...args: any[]): Promise<JSHandl
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  pageFunction | Function \| string |  |
-|  args | any\[\] |  |
+|  pageFunction | Function \| string | Function to be evaluated in the page context. |
+|  args | any\[\] | Arguments to pass to <code>pageFunction</code>. |
 
 <b>Returns:</b>
 
 Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
 
+Promise which resolves to the return value of `pageFunction`<!-- -->.
+

new-docs/puppeteer.webworker.executioncontext.md

@@ -4,6 +4,8 @@
 
 ## WebWorker.executionContext() method
 
+Returns the ExecutionContext the WebWorker runs in
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,5 @@ executionContext(): Promise<ExecutionContext>;
 
 Promise&lt;[ExecutionContext](./puppeteer.executioncontext.md)<!-- -->&gt;
 
+The ExecutionContext the web worker runs in.
+

new-docs/puppeteer.webworker.md

@@ -4,17 +4,33 @@
 
 ## WebWorker class
 
+The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class WebWorker extends EventEmitter 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(client, url, consoleAPICalled, exceptionThrown)](./puppeteer.webworker._constructor_.md) |  | Constructs a new instance of the <code>WebWorker</code> class |
+The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `WebWorker` class.
+
+## Example
+
+
+```js
+page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
+page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));
+
+console.log('Current workers:');
+for (const worker of page.workers()) {
+  console.log('  ' + worker.url());
+}
+
+```
 
 ## Properties
 
@@ -29,8 +45,8 @@ export declare class WebWorker extends EventEmitter
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [evaluate(pageFunction, args)](./puppeteer.webworker.evaluate.md) |  |  |
-|  [evaluateHandle(pageFunction, args)](./puppeteer.webworker.evaluatehandle.md) |  |  |
-|  [executionContext()](./puppeteer.webworker.executioncontext.md) |  |  |
+|  [evaluate(pageFunction, args)](./puppeteer.webworker.evaluate.md) |  | If the function passed to the <code>worker.evaluate</code> returns a Promise, then <code>worker.evaluate</code> would wait for the promise to resolve and return its value. If the function passed to the <code>worker.evaluate</code> returns a non-serializable value, then <code>worker.evaluate</code> resolves to <code>undefined</code>. DevTools Protocol also supports transferring some additional values that are not serializable by <code>JSON</code>: <code>-0</code>, <code>NaN</code>, <code>Infinity</code>, <code>-Infinity</code>, and bigint literals. Shortcut for <code>await worker.executionContext()).evaluate(pageFunction, ...args)</code>. |
+|  [evaluateHandle(pageFunction, args)](./puppeteer.webworker.evaluatehandle.md) |  | The only difference between <code>worker.evaluate</code> and <code>worker.evaluateHandle</code> is that <code>worker.evaluateHandle</code> returns in-page object (JSHandle). If the function passed to the <code>worker.evaluateHandle</code> returns a \[Promise\], then <code>worker.evaluateHandle</code> would wait for the promise to resolve and return its value. Shortcut for \[(await worker.executionContext()).evaluateHandle(pageFunction, ...args)\](\#executioncontextevaluatehandlepagefunction-args). |
+|  [executionContext()](./puppeteer.webworker.executioncontext.md) |  | Returns the ExecutionContext the WebWorker runs in |
 |  [url()](./puppeteer.webworker.url.md) |  |  |
 

new-docs/puppeteer.webworker.url.md

@@ -13,3 +13,5 @@ url(): string;
 
 string
 
+The URL of this web worker.
+

src/WebWorker.ts

@@ -30,12 +30,35 @@ type ExceptionThrownCallback = (
 ) => void;
 type JSHandleFactory = (obj: Protocol.Runtime.RemoteObject) => JSHandle;
 
+/**
+ * The WebWorker class represents a {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker}.
+ *
+ * @remarks
+ * The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle.
+ *
+ * @example
+ * ```js
+ * page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
+ * page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));
+ *
+ * console.log('Current workers:');
+ * for (const worker of page.workers()) {
+ *   console.log('  ' + worker.url());
+ * }
+ * ```
+ *
+ * @public
+ */
 export class WebWorker extends EventEmitter {
   _client: CDPSession;
   _url: string;
   _executionContextPromise: Promise<ExecutionContext>;
   _executionContextCallback: (value: ExecutionContext) => void;
 
+  /**
+   *
+   * @internal
+   */
   constructor(
     client: CDPSession,
     url: string,
@@ -76,14 +99,30 @@ export class WebWorker extends EventEmitter {
     );
   }
 
+  /**
+   * @returns The URL of this web worker.
+   */
   url(): string {
     return this._url;
   }
 
+  /**
+   * Returns the ExecutionContext the WebWorker runs in
+   * @returns The ExecutionContext the web worker runs in.
+   */
   async executionContext(): Promise<ExecutionContext> {
     return this._executionContextPromise;
   }
 
+  /**
+   * If the function passed to the `worker.evaluate` returns a Promise, then `worker.evaluate` would wait for the promise to resolve and return its value.
+   * If the function passed to the `worker.evaluate` returns a non-serializable value, then `worker.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.
+   * Shortcut for `await worker.executionContext()).evaluate(pageFunction, ...args)`.
+   *
+   * @param pageFunction - Function to be evaluated in the worker context.
+   * @param args - Arguments to pass to `pageFunction`.
+   * @returns Promise which resolves to the return value of `pageFunction`.
+   */
   async evaluate<ReturnType extends any>(
     pageFunction: Function | string,
     ...args: any[]
@@ -94,6 +133,14 @@ export class WebWorker extends EventEmitter {
     );
   }
 
+  /**
+   * The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns in-page object (JSHandle).
+   * If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for the promise to resolve and return its value.
+   * Shortcut for [(await worker.executionContext()).evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args).
+   * @param pageFunction - Function to be evaluated in the page context.
+   * @param args - Arguments to pass to `pageFunction`.
+   * @returns Promise which resolves to the return value of `pageFunction`.
+   */
   async evaluateHandle(
     pageFunction: Function | string,
     ...args: any[]