docs(new): migrate CDPSession to TSDoc (#6064)

src/common/Connection.ts

@@ -167,12 +167,44 @@ interface CDPSessionOnMessageObject {
   error: { message: string; data: any };
   result?: any;
 }
-export class CDPSession extends EventEmitter {
-  _connection: Connection;
-  _sessionId: string;
-  _targetType: string;
-  _callbacks: Map<number, ConnectionCallback> = new Map();
 
+/**
+ * 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;
+  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(