From 983a7b67df65b918738c095cdb2e2e4ca3af4c17 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Mon, 22 Jun 2020 12:05:10 +0200 Subject: [PATCH] docs(new): migrate CDPSession to TSDoc (#6064) --- new-docs/puppeteer.cdpsession._callbacks.md | 11 ----- new-docs/puppeteer.cdpsession._connection.md | 11 ----- .../puppeteer.cdpsession._constructor_.md | 22 --------- new-docs/puppeteer.cdpsession._onclosed.md | 15 ------ new-docs/puppeteer.cdpsession._onmessage.md | 22 --------- new-docs/puppeteer.cdpsession._sessionid.md | 11 ----- new-docs/puppeteer.cdpsession._targettype.md | 11 ----- new-docs/puppeteer.cdpsession.detach.md | 2 + new-docs/puppeteer.cdpsession.md | 36 ++++++++------ new-docs/puppeteer.md | 2 +- src/common/Connection.ts | 48 +++++++++++++++++-- 11 files changed, 70 insertions(+), 121 deletions(-) delete mode 100644 new-docs/puppeteer.cdpsession._callbacks.md delete mode 100644 new-docs/puppeteer.cdpsession._connection.md delete mode 100644 new-docs/puppeteer.cdpsession._constructor_.md delete mode 100644 new-docs/puppeteer.cdpsession._onclosed.md delete mode 100644 new-docs/puppeteer.cdpsession._onmessage.md delete mode 100644 new-docs/puppeteer.cdpsession._sessionid.md delete mode 100644 new-docs/puppeteer.cdpsession._targettype.md diff --git a/new-docs/puppeteer.cdpsession._callbacks.md b/new-docs/puppeteer.cdpsession._callbacks.md deleted file mode 100644 index 2bf6a5ac7f06b..0000000000000 --- a/new-docs/puppeteer.cdpsession._callbacks.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [CDPSession](./puppeteer.cdpsession.md) > [\_callbacks](./puppeteer.cdpsession._callbacks.md) - -## CDPSession.\_callbacks property - -Signature: - -```typescript -_callbacks: Map; -``` diff --git a/new-docs/puppeteer.cdpsession._connection.md b/new-docs/puppeteer.cdpsession._connection.md deleted file mode 100644 index 63538e1f319cb..0000000000000 --- a/new-docs/puppeteer.cdpsession._connection.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [CDPSession](./puppeteer.cdpsession.md) > [\_connection](./puppeteer.cdpsession._connection.md) - -## CDPSession.\_connection property - -Signature: - -```typescript -_connection: Connection; -``` diff --git a/new-docs/puppeteer.cdpsession._constructor_.md b/new-docs/puppeteer.cdpsession._constructor_.md deleted file mode 100644 index 352e10b0aff4d..0000000000000 --- a/new-docs/puppeteer.cdpsession._constructor_.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [CDPSession](./puppeteer.cdpsession.md) > [(constructor)](./puppeteer.cdpsession._constructor_.md) - -## CDPSession.(constructor) - -Constructs a new instance of the `CDPSession` class - -Signature: - -```typescript -constructor(connection: Connection, targetType: string, sessionId: string); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| connection | [Connection](./puppeteer.connection.md) | | -| targetType | string | | -| sessionId | string | | - diff --git a/new-docs/puppeteer.cdpsession._onclosed.md b/new-docs/puppeteer.cdpsession._onclosed.md deleted file mode 100644 index fb352da45183c..0000000000000 --- a/new-docs/puppeteer.cdpsession._onclosed.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [CDPSession](./puppeteer.cdpsession.md) > [\_onClosed](./puppeteer.cdpsession._onclosed.md) - -## CDPSession.\_onClosed() method - -Signature: - -```typescript -_onClosed(): void; -``` -Returns: - -void - diff --git a/new-docs/puppeteer.cdpsession._onmessage.md b/new-docs/puppeteer.cdpsession._onmessage.md deleted file mode 100644 index 6aae52baafada..0000000000000 --- a/new-docs/puppeteer.cdpsession._onmessage.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [CDPSession](./puppeteer.cdpsession.md) > [\_onMessage](./puppeteer.cdpsession._onmessage.md) - -## CDPSession.\_onMessage() method - -Signature: - -```typescript -_onMessage(object: CDPSessionOnMessageObject): void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| object | CDPSessionOnMessageObject | | - -Returns: - -void - diff --git a/new-docs/puppeteer.cdpsession._sessionid.md b/new-docs/puppeteer.cdpsession._sessionid.md deleted file mode 100644 index 1600de19c7a90..0000000000000 --- a/new-docs/puppeteer.cdpsession._sessionid.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [CDPSession](./puppeteer.cdpsession.md) > [\_sessionId](./puppeteer.cdpsession._sessionid.md) - -## CDPSession.\_sessionId property - -Signature: - -```typescript -_sessionId: string; -``` diff --git a/new-docs/puppeteer.cdpsession._targettype.md b/new-docs/puppeteer.cdpsession._targettype.md deleted file mode 100644 index 5ab6ed09a1608..0000000000000 --- a/new-docs/puppeteer.cdpsession._targettype.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [CDPSession](./puppeteer.cdpsession.md) > [\_targetType](./puppeteer.cdpsession._targettype.md) - -## CDPSession.\_targetType property - -Signature: - -```typescript -_targetType: string; -``` diff --git a/new-docs/puppeteer.cdpsession.detach.md b/new-docs/puppeteer.cdpsession.detach.md index bd7772bd23f06..40856a9cbe1b9 100644 --- a/new-docs/puppeteer.cdpsession.detach.md +++ b/new-docs/puppeteer.cdpsession.detach.md @@ -4,6 +4,8 @@ ## CDPSession.detach() method +Detaches the cdpSession from the target. Once detached, the cdpSession object won't emit any events and can't be used to send messages. + Signature: ```typescript diff --git a/new-docs/puppeteer.cdpsession.md b/new-docs/puppeteer.cdpsession.md index 1f3987c67c37b..038b0bda54fd2 100644 --- a/new-docs/puppeteer.cdpsession.md +++ b/new-docs/puppeteer.cdpsession.md @@ -4,6 +4,8 @@ ## CDPSession class +The `CDPSession` instances are used to talk raw Chrome Devtools Protocol. + Signature: ```typescript @@ -11,27 +13,33 @@ export declare class CDPSession extends EventEmitter ``` Extends: [EventEmitter](./puppeteer.eventemitter.md) -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(connection, targetType, sessionId)](./puppeteer.cdpsession._constructor_.md) | | Constructs a new instance of the CDPSession class | +Protocol methods can be called with [CDPSession.send()](./puppeteer.cdpsession.send.md) method and protocol events can be subscribed to with `CDPSession.on` method. + +Useful links: [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/) and [Getting Started with DevTools Protocol](https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md). + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `CDPSession` class. -## Properties +## Example -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [\_callbacks](./puppeteer.cdpsession._callbacks.md) | | Map<number, ConnectionCallback> | | -| [\_connection](./puppeteer.cdpsession._connection.md) | | [Connection](./puppeteer.connection.md) | | -| [\_sessionId](./puppeteer.cdpsession._sessionid.md) | | string | | -| [\_targetType](./puppeteer.cdpsession._targettype.md) | | string | | + +```js +const client = await page.target().createCDPSession(); +await client.send('Animation.enable'); +client.on('Animation.animationCreated', () => console.log('Animation created!')); +const response = await client.send('Animation.getPlaybackRate'); +console.log('playback rate is ' + response.playbackRate); +await client.send('Animation.setPlaybackRate', { + playbackRate: response.playbackRate / 2 +}); + +``` ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [\_onClosed()](./puppeteer.cdpsession._onclosed.md) | | | -| [\_onMessage(object)](./puppeteer.cdpsession._onmessage.md) | | | -| [detach()](./puppeteer.cdpsession.detach.md) | | | +| [detach()](./puppeteer.cdpsession.detach.md) | | Detaches the cdpSession from the target. Once detached, the cdpSession object won't emit any events and can't be used to send messages. | | [send(method, params)](./puppeteer.cdpsession.send.md) | | | diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index d6ba6af699f70..7310739d8c2a6 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -12,7 +12,7 @@ | [Browser](./puppeteer.browser.md) | | | [BrowserContext](./puppeteer.browsercontext.md) | | | [BrowserFetcher](./puppeteer.browserfetcher.md) | | -| [CDPSession](./puppeteer.cdpsession.md) | | +| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | | [Connection](./puppeteer.connection.md) | | | [ConsoleMessage](./puppeteer.consolemessage.md) | | | [Coverage](./puppeteer.coverage.md) | | diff --git a/src/common/Connection.ts b/src/common/Connection.ts index 9ef4ab6ccd239..dcf22d6788394 100644 --- a/src/common/Connection.ts +++ b/src/common/Connection.ts @@ -167,12 +167,44 @@ interface CDPSessionOnMessageObject { error: { message: string; data: any }; result?: any; } + +/** + * The `CDPSession` instances are used to talk raw Chrome Devtools Protocol. + * + * @remarks + * + * Protocol methods can be called with {@link CDPSession.send} method and protocol + * events can be subscribed to with `CDPSession.on` method. + * + * Useful links: {@link https://chromedevtools.github.io/devtools-protocol/ | DevTools Protocol Viewer} + * and {@link https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md | Getting Started with DevTools Protocol}. + * + * @example + * ```js + * const client = await page.target().createCDPSession(); + * await client.send('Animation.enable'); + * client.on('Animation.animationCreated', () => console.log('Animation created!')); + * const response = await client.send('Animation.getPlaybackRate'); + * console.log('playback rate is ' + response.playbackRate); + * await client.send('Animation.setPlaybackRate', { + * playbackRate: response.playbackRate / 2 + * }); + * ``` + * + * @public + */ export class CDPSession extends EventEmitter { + /** + * @internal + */ _connection: Connection; - _sessionId: string; - _targetType: string; - _callbacks: Map = new Map(); + private _sessionId: string; + private _targetType: string; + private _callbacks: Map = new Map(); + /** + * @internal + */ constructor(connection: Connection, targetType: string, sessionId: string) { super(); this._connection = connection; @@ -206,6 +238,9 @@ export class CDPSession extends EventEmitter { }); } + /** + * @internal + */ _onMessage(object: CDPSessionOnMessageObject): void { if (object.id && this._callbacks.has(object.id)) { const callback = this._callbacks.get(object.id); @@ -221,6 +256,10 @@ export class CDPSession extends EventEmitter { } } + /** + * Detaches the cdpSession from the target. Once detached, the cdpSession object + * won't emit any events and can't be used to send messages. + */ async detach(): Promise { if (!this._connection) throw new Error( @@ -231,6 +270,9 @@ export class CDPSession extends EventEmitter { }); } + /** + * @internal + */ _onClosed(): void { for (const callback of this._callbacks.values()) callback.reject(