docs(new): migrate CDPSession to TSDoc

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.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.cdpsession.md

@@ -4,34 +4,42 @@
 
 ## CDPSession class
 
+The `CDPSession` instances are used to talk raw Chrome Devtools Protocol.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class CDPSession extends EventEmitter 
 ```
 <b>Extends:</b> [EventEmitter](./puppeteer.eventemitter.md)
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(connection, targetType, sessionId)](./puppeteer.cdpsession._constructor_.md) |  | Constructs a new instance of the <code>CDPSession</code> 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&lt;number, ConnectionCallback&gt; |  |
-|  [\_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) |  |  |
 

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 <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. |
 |  [Connection](./puppeteer.connection.md) |  |
 |  [ConsoleMessage](./puppeteer.consolemessage.md) |  |
 |  [Coverage](./puppeteer.coverage.md) |  |

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<number, ConnectionCallback> = new Map();
+  private _sessionId: string;
+  private _targetType: string;
+  private _callbacks: Map<number, ConnectionCallback> = 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<void> {
     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(