docs(new): migrate Target to TSDoc (#6067)

* docs(new): migrate Target to TSDoc

Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>

new-docs/puppeteer.target._browsercontext.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_browserContext](./puppeteer.target._browsercontext.md)
-
-## Target.\_browserContext property
-
-<b>Signature:</b>
-
-```typescript
-_browserContext: BrowserContext;
-```

new-docs/puppeteer.target._closedcallback.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_closedCallback](./puppeteer.target._closedcallback.md)
-
-## Target.\_closedCallback property
-
-<b>Signature:</b>
-
-```typescript
-_closedCallback: () => void;
-```

new-docs/puppeteer.target._constructor_.md

@@ -1,24 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [(constructor)](./puppeteer.target._constructor_.md)
-
-## Target.(constructor)
-
-Constructs a new instance of the `Target` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(targetInfo: Protocol.Target.TargetInfo, browserContext: BrowserContext, sessionFactory: () => Promise<CDPSession>, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  targetInfo | Protocol.Target.TargetInfo |  |
-|  browserContext | [BrowserContext](./puppeteer.browsercontext.md) |  |
-|  sessionFactory | () =&gt; Promise&lt;[CDPSession](./puppeteer.cdpsession.md)<!-- -->&gt; |  |
-|  ignoreHTTPSErrors | boolean |  |
-|  defaultViewport | Viewport \| null |  |
-

new-docs/puppeteer.target._defaultviewport.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_defaultViewport](./puppeteer.target._defaultviewport.md)
-
-## Target.\_defaultViewport property
-
-<b>Signature:</b>
-
-```typescript
-_defaultViewport?: Viewport;
-```

new-docs/puppeteer.target._ignorehttpserrors.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_ignoreHTTPSErrors](./puppeteer.target._ignorehttpserrors.md)
-
-## Target.\_ignoreHTTPSErrors property
-
-<b>Signature:</b>
-
-```typescript
-_ignoreHTTPSErrors: boolean;
-```

new-docs/puppeteer.target._initializedcallback.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_initializedCallback](./puppeteer.target._initializedcallback.md)
-
-## Target.\_initializedCallback property
-
-<b>Signature:</b>
-
-```typescript
-_initializedCallback: (x: boolean) => void;
-```

new-docs/puppeteer.target._initializedpromise.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_initializedPromise](./puppeteer.target._initializedpromise.md)
-
-## Target.\_initializedPromise property
-
-<b>Signature:</b>
-
-```typescript
-_initializedPromise: Promise<boolean>;
-```

new-docs/puppeteer.target._isclosedpromise.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_isClosedPromise](./puppeteer.target._isclosedpromise.md)
-
-## Target.\_isClosedPromise property
-
-<b>Signature:</b>
-
-```typescript
-_isClosedPromise: Promise<boolean>;
-```

new-docs/puppeteer.target._isinitialized.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_isInitialized](./puppeteer.target._isinitialized.md)
-
-## Target.\_isInitialized property
-
-<b>Signature:</b>
-
-```typescript
-_isInitialized: boolean;
-```

new-docs/puppeteer.target._pagepromise.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_pagePromise](./puppeteer.target._pagepromise.md)
-
-## Target.\_pagePromise property
-
-<b>Signature:</b>
-
-```typescript
-_pagePromise?: Promise<Page>;
-```

new-docs/puppeteer.target._sessionfactory.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_sessionFactory](./puppeteer.target._sessionfactory.md)
-
-## Target.\_sessionFactory property
-
-<b>Signature:</b>
-
-```typescript
-_sessionFactory: () => Promise<CDPSession>;
-```

new-docs/puppeteer.target._targetid.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_targetId](./puppeteer.target._targetid.md)
-
-## Target.\_targetId property
-
-<b>Signature:</b>
-
-```typescript
-_targetId: string;
-```

new-docs/puppeteer.target._targetinfo.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_targetInfo](./puppeteer.target._targetinfo.md)
-
-## Target.\_targetInfo property
-
-<b>Signature:</b>
-
-```typescript
-_targetInfo: Protocol.Target.TargetInfo;
-```

new-docs/puppeteer.target._targetinfochanged.md

@@ -1,22 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_targetInfoChanged](./puppeteer.target._targetinfochanged.md)
-
-## Target.\_targetInfoChanged() method
-
-<b>Signature:</b>
-
-```typescript
-_targetInfoChanged(targetInfo: Protocol.Target.TargetInfo): void;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  targetInfo | Protocol.Target.TargetInfo |  |
-
-<b>Returns:</b>
-
-void
-

new-docs/puppeteer.target._workerpromise.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Target](./puppeteer.target.md) &gt; [\_workerPromise](./puppeteer.target._workerpromise.md)
-
-## Target.\_workerPromise property
-
-<b>Signature:</b>
-
-```typescript
-_workerPromise?: Promise<WebWorker>;
-```

new-docs/puppeteer.target.browser.md

@@ -4,6 +4,8 @@
 
 ## Target.browser() method
 
+Get the browser the target belongs to.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.target.createcdpsession.md

@@ -4,6 +4,8 @@
 
 ## Target.createCDPSession() method
 
+Creates a Chrome Devtools Protocol session attached to the target.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.target.md

@@ -10,41 +10,20 @@
 export declare class Target 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Target` class.
-|  --- | --- | --- |
-|  [(constructor)(targetInfo, browserContext, sessionFactory, ignoreHTTPSErrors, defaultViewport)](./puppeteer.target._constructor_.md) |  | Constructs a new instance of the <code>Target</code> class |
-
-## Properties
-
-|  Property | Modifiers | Type | Description |
-|  --- | --- | --- | --- |
-|  [\_browserContext](./puppeteer.target._browsercontext.md) |  | [BrowserContext](./puppeteer.browsercontext.md) |  |
-|  [\_closedCallback](./puppeteer.target._closedcallback.md) |  | () =&gt; void |  |
-|  [\_defaultViewport](./puppeteer.target._defaultviewport.md) |  | Viewport |  |
-|  [\_ignoreHTTPSErrors](./puppeteer.target._ignorehttpserrors.md) |  | boolean |  |
-|  [\_initializedCallback](./puppeteer.target._initializedcallback.md) |  | (x: boolean) =&gt; void |  |
-|  [\_initializedPromise](./puppeteer.target._initializedpromise.md) |  | Promise&lt;boolean&gt; |  |
-|  [\_isClosedPromise](./puppeteer.target._isclosedpromise.md) |  | Promise&lt;boolean&gt; |  |
-|  [\_isInitialized](./puppeteer.target._isinitialized.md) |  | boolean |  |
-|  [\_pagePromise](./puppeteer.target._pagepromise.md) |  | Promise&lt;[Page](./puppeteer.page.md)<!-- -->&gt; |  |
-|  [\_sessionFactory](./puppeteer.target._sessionfactory.md) |  | () =&gt; Promise&lt;[CDPSession](./puppeteer.cdpsession.md)<!-- -->&gt; |  |
-|  [\_targetId](./puppeteer.target._targetid.md) |  | string |  |
-|  [\_targetInfo](./puppeteer.target._targetinfo.md) |  | Protocol.Target.TargetInfo |  |
-|  [\_workerPromise](./puppeteer.target._workerpromise.md) |  | Promise&lt;[WebWorker](./puppeteer.webworker.md)<!-- -->&gt; |  |
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [\_targetInfoChanged(targetInfo)](./puppeteer.target._targetinfochanged.md) |  |  |
+|  [browser()](./puppeteer.target.browser.md) |  | Get the browser the target belongs to. |
-|  [browser()](./puppeteer.target.browser.md) |  |  |
 |  [browserContext()](./puppeteer.target.browsercontext.md) |  |  |
-|  [createCDPSession()](./puppeteer.target.createcdpsession.md) |  |  |
+|  [createCDPSession()](./puppeteer.target.createcdpsession.md) |  | Creates a Chrome Devtools Protocol session attached to the target. |
-|  [opener()](./puppeteer.target.opener.md) |  |  |
+|  [opener()](./puppeteer.target.opener.md) |  | Get the target that opened this target. Top-level targets return <code>null</code>. |
-|  [page()](./puppeteer.target.page.md) |  |  |
+|  [page()](./puppeteer.target.page.md) |  | If the target is not of type <code>&quot;page&quot;</code> or <code>&quot;background_page&quot;</code>, returns <code>null</code>. |
-|  [type()](./puppeteer.target.type.md) |  |  |
+|  [type()](./puppeteer.target.type.md) |  | Identifies what kind of target this is. |
 |  [url()](./puppeteer.target.url.md) |  |  |
-|  [worker()](./puppeteer.target.worker.md) |  |  |
+|  [worker()](./puppeteer.target.worker.md) |  | If the target is not of type <code>&quot;service_worker&quot;</code> or <code>&quot;shared_worker&quot;</code>, returns <code>null</code>. |
 

new-docs/puppeteer.target.opener.md

@@ -4,6 +4,8 @@
 
 ## Target.opener() method
 
+Get the target that opened this target. Top-level targets return `null`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.target.page.md

@@ -4,6 +4,8 @@
 
 ## Target.page() method
 
+If the target is not of type `"page"` or `"background_page"`<!-- -->, returns `null`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.target.type.md

@@ -4,6 +4,8 @@
 
 ## Target.type() method
 
+Identifies what kind of target this is.
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,7 @@ type(): 'page' | 'background_page' | 'service_worker' | 'shared_worker' | 'other
 
 'page' \| 'background\_page' \| 'service\_worker' \| 'shared\_worker' \| 'other' \| 'browser' \| 'webview'
 
+## Remarks
+
+See [docs](https://developer.chrome.com/extensions/background_pages) for more info about background pages.
+

new-docs/puppeteer.target.worker.md

@@ -4,6 +4,8 @@
 
 ## Target.worker() method
 
+If the target is not of type `"service_worker"` or `"shared_worker"`<!-- -->, returns `null`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript

src/common/Target.ts

@@ -23,20 +23,42 @@ import { Viewport } from './PuppeteerViewport';
 import Protocol from '../protocol';
 
 export class Target {
-  _targetInfo: Protocol.Target.TargetInfo;
+  private _targetInfo: Protocol.Target.TargetInfo;
-  _browserContext: BrowserContext;
+  private _browserContext: BrowserContext;
-  _targetId: string;
-  _sessionFactory: () => Promise<CDPSession>;
-  _ignoreHTTPSErrors: boolean;
-  _defaultViewport?: Viewport;
-  _pagePromise?: Promise<Page>;
-  _workerPromise?: Promise<WebWorker>;
-  _initializedPromise: Promise<boolean>;
-  _initializedCallback: (x: boolean) => void;
-  _isClosedPromise: Promise<boolean>;
-  _closedCallback: () => void;
-  _isInitialized: boolean;
 
+  private _sessionFactory: () => Promise<CDPSession>;
+  private _ignoreHTTPSErrors: boolean;
+  private _defaultViewport?: Viewport;
+  private _pagePromise?: Promise<Page>;
+  private _workerPromise?: Promise<WebWorker>;
+  /**
+   * @internal
+   */
+  _initializedPromise: Promise<boolean>;
+  /**
+   * @internal
+   */
+  _initializedCallback: (x: boolean) => void;
+  /**
+   * @internal
+   */
+  _isClosedPromise: Promise<boolean>;
+  /**
+   * @internal
+   */
+  _closedCallback: () => void;
+  /**
+   * @internal
+   */
+  _isInitialized: boolean;
+  /**
+   * @internal
+   */
+  _targetId: string;
+
+  /**
+   * @internal
+   */
   constructor(
     targetInfo: Protocol.Target.TargetInfo,
     browserContext: BrowserContext,
@@ -75,10 +97,16 @@ export class Target {
     if (this._isInitialized) this._initializedCallback(true);
   }
 
+  /**
+   * Creates a Chrome Devtools Protocol session attached to the target.
+   */
   createCDPSession(): Promise<CDPSession> {
     return this._sessionFactory();
   }
 
+  /**
+   * If the target is not of type `"page"` or `"background_page"`, returns `null`.
+   */
   async page(): Promise<Page | null> {
     if (
       (this._targetInfo.type === 'page' ||
@@ -98,6 +126,9 @@ export class Target {
     return this._pagePromise;
   }
 
+  /**
+   * If the target is not of type `"service_worker"` or `"shared_worker"`, returns `null`.
+   */
   async worker(): Promise<WebWorker | null> {
     if (
       this._targetInfo.type !== 'service_worker' &&
@@ -123,6 +154,13 @@ export class Target {
     return this._targetInfo.url;
   }
 
+  /**
+   * Identifies what kind of target this is.
+   *
+   * @remarks
+   *
+   * See {@link https://developer.chrome.com/extensions/background_pages | docs} for more info about background pages.
+   */
   type():
     | 'page'
     | 'background_page'
@@ -144,6 +182,9 @@ export class Target {
     return 'other';
   }
 
+  /**
+   * Get the browser the target belongs to.
+   */
   browser(): Browser {
     return this._browserContext.browser();
   }
@@ -152,12 +193,18 @@ export class Target {
     return this._browserContext;
   }
 
+  /**
+   * Get the target that opened this target. Top-level targets return `null`.
+   */
   opener(): Target | null {
     const { openerId } = this._targetInfo;
     if (!openerId) return null;
     return this.browser()._targets.get(openerId);
   }
 
+  /**
+   * @internal
+   */
   _targetInfoChanged(targetInfo: Protocol.Target.TargetInfo): void {
     this._targetInfo = targetInfo;