Skip to content
Permalink
Browse files

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

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

Co-authored-by: martinsplitt <martin@geekonaut.de>
  • Loading branch information
AVGP and martinsplitt committed Jun 17, 2020
1 parent 64c9c70 commit 44402b75a04410a71611246f7c0347dfb98282f8
@@ -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

This file was deleted.

@@ -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`<!-- -->.
@@ -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`<!-- -->.

@@ -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.

@@ -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) | | |

@@ -13,3 +13,5 @@ url(): string;

string

The URL of this web worker.

@@ -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[]

0 comments on commit 44402b7

Please sign in to comment.
You can’t perform that action at this time.