From 7025f1c5eabc5616b95124737e5789e0802f9bb3 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Mon, 22 Jun 2020 14:57:04 +0200 Subject: [PATCH] docs(new): migrate Target to TSDoc (#6067) * docs(new): migrate Target to TSDoc Co-authored-by: Alex Rudenko --- new-docs/puppeteer.target._browsercontext.md | 11 ---- new-docs/puppeteer.target._closedcallback.md | 11 ---- new-docs/puppeteer.target._constructor_.md | 24 ------- new-docs/puppeteer.target._defaultviewport.md | 11 ---- .../puppeteer.target._ignorehttpserrors.md | 11 ---- .../puppeteer.target._initializedcallback.md | 11 ---- .../puppeteer.target._initializedpromise.md | 11 ---- new-docs/puppeteer.target._isclosedpromise.md | 11 ---- new-docs/puppeteer.target._isinitialized.md | 11 ---- new-docs/puppeteer.target._pagepromise.md | 11 ---- new-docs/puppeteer.target._sessionfactory.md | 11 ---- new-docs/puppeteer.target._targetid.md | 11 ---- new-docs/puppeteer.target._targetinfo.md | 11 ---- .../puppeteer.target._targetinfochanged.md | 22 ------- new-docs/puppeteer.target._workerpromise.md | 11 ---- new-docs/puppeteer.target.browser.md | 2 + new-docs/puppeteer.target.createcdpsession.md | 2 + new-docs/puppeteer.target.md | 37 +++-------- new-docs/puppeteer.target.opener.md | 2 + new-docs/puppeteer.target.page.md | 2 + new-docs/puppeteer.target.type.md | 6 ++ new-docs/puppeteer.target.worker.md | 2 + src/common/Target.ts | 63 ++++++++++++++++--- 23 files changed, 79 insertions(+), 226 deletions(-) delete mode 100644 new-docs/puppeteer.target._browsercontext.md delete mode 100644 new-docs/puppeteer.target._closedcallback.md delete mode 100644 new-docs/puppeteer.target._constructor_.md delete mode 100644 new-docs/puppeteer.target._defaultviewport.md delete mode 100644 new-docs/puppeteer.target._ignorehttpserrors.md delete mode 100644 new-docs/puppeteer.target._initializedcallback.md delete mode 100644 new-docs/puppeteer.target._initializedpromise.md delete mode 100644 new-docs/puppeteer.target._isclosedpromise.md delete mode 100644 new-docs/puppeteer.target._isinitialized.md delete mode 100644 new-docs/puppeteer.target._pagepromise.md delete mode 100644 new-docs/puppeteer.target._sessionfactory.md delete mode 100644 new-docs/puppeteer.target._targetid.md delete mode 100644 new-docs/puppeteer.target._targetinfo.md delete mode 100644 new-docs/puppeteer.target._targetinfochanged.md delete mode 100644 new-docs/puppeteer.target._workerpromise.md diff --git a/new-docs/puppeteer.target._browsercontext.md b/new-docs/puppeteer.target._browsercontext.md deleted file mode 100644 index a30aeed7d1915..0000000000000 --- a/new-docs/puppeteer.target._browsercontext.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_browserContext](./puppeteer.target._browsercontext.md) - -## Target.\_browserContext property - -Signature: - -```typescript -_browserContext: BrowserContext; -``` diff --git a/new-docs/puppeteer.target._closedcallback.md b/new-docs/puppeteer.target._closedcallback.md deleted file mode 100644 index 05f7573559bef..0000000000000 --- a/new-docs/puppeteer.target._closedcallback.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_closedCallback](./puppeteer.target._closedcallback.md) - -## Target.\_closedCallback property - -Signature: - -```typescript -_closedCallback: () => void; -``` diff --git a/new-docs/puppeteer.target._constructor_.md b/new-docs/puppeteer.target._constructor_.md deleted file mode 100644 index a4cd09446c1ff..0000000000000 --- a/new-docs/puppeteer.target._constructor_.md +++ /dev/null @@ -1,24 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [(constructor)](./puppeteer.target._constructor_.md) - -## Target.(constructor) - -Constructs a new instance of the `Target` class - -Signature: - -```typescript -constructor(targetInfo: Protocol.Target.TargetInfo, browserContext: BrowserContext, sessionFactory: () => Promise, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| targetInfo | Protocol.Target.TargetInfo | | -| browserContext | [BrowserContext](./puppeteer.browsercontext.md) | | -| sessionFactory | () => Promise<[CDPSession](./puppeteer.cdpsession.md)> | | -| ignoreHTTPSErrors | boolean | | -| defaultViewport | Viewport \| null | | - diff --git a/new-docs/puppeteer.target._defaultviewport.md b/new-docs/puppeteer.target._defaultviewport.md deleted file mode 100644 index dfd34df67733e..0000000000000 --- a/new-docs/puppeteer.target._defaultviewport.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_defaultViewport](./puppeteer.target._defaultviewport.md) - -## Target.\_defaultViewport property - -Signature: - -```typescript -_defaultViewport?: Viewport; -``` diff --git a/new-docs/puppeteer.target._ignorehttpserrors.md b/new-docs/puppeteer.target._ignorehttpserrors.md deleted file mode 100644 index b9fc0868f7447..0000000000000 --- a/new-docs/puppeteer.target._ignorehttpserrors.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_ignoreHTTPSErrors](./puppeteer.target._ignorehttpserrors.md) - -## Target.\_ignoreHTTPSErrors property - -Signature: - -```typescript -_ignoreHTTPSErrors: boolean; -``` diff --git a/new-docs/puppeteer.target._initializedcallback.md b/new-docs/puppeteer.target._initializedcallback.md deleted file mode 100644 index 697191a35d4ea..0000000000000 --- a/new-docs/puppeteer.target._initializedcallback.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_initializedCallback](./puppeteer.target._initializedcallback.md) - -## Target.\_initializedCallback property - -Signature: - -```typescript -_initializedCallback: (x: boolean) => void; -``` diff --git a/new-docs/puppeteer.target._initializedpromise.md b/new-docs/puppeteer.target._initializedpromise.md deleted file mode 100644 index e45f784e003f9..0000000000000 --- a/new-docs/puppeteer.target._initializedpromise.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_initializedPromise](./puppeteer.target._initializedpromise.md) - -## Target.\_initializedPromise property - -Signature: - -```typescript -_initializedPromise: Promise; -``` diff --git a/new-docs/puppeteer.target._isclosedpromise.md b/new-docs/puppeteer.target._isclosedpromise.md deleted file mode 100644 index 1860101acc938..0000000000000 --- a/new-docs/puppeteer.target._isclosedpromise.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_isClosedPromise](./puppeteer.target._isclosedpromise.md) - -## Target.\_isClosedPromise property - -Signature: - -```typescript -_isClosedPromise: Promise; -``` diff --git a/new-docs/puppeteer.target._isinitialized.md b/new-docs/puppeteer.target._isinitialized.md deleted file mode 100644 index ce872c064d19a..0000000000000 --- a/new-docs/puppeteer.target._isinitialized.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_isInitialized](./puppeteer.target._isinitialized.md) - -## Target.\_isInitialized property - -Signature: - -```typescript -_isInitialized: boolean; -``` diff --git a/new-docs/puppeteer.target._pagepromise.md b/new-docs/puppeteer.target._pagepromise.md deleted file mode 100644 index 3ad61130725fa..0000000000000 --- a/new-docs/puppeteer.target._pagepromise.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_pagePromise](./puppeteer.target._pagepromise.md) - -## Target.\_pagePromise property - -Signature: - -```typescript -_pagePromise?: Promise; -``` diff --git a/new-docs/puppeteer.target._sessionfactory.md b/new-docs/puppeteer.target._sessionfactory.md deleted file mode 100644 index 649c64cb4936b..0000000000000 --- a/new-docs/puppeteer.target._sessionfactory.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_sessionFactory](./puppeteer.target._sessionfactory.md) - -## Target.\_sessionFactory property - -Signature: - -```typescript -_sessionFactory: () => Promise; -``` diff --git a/new-docs/puppeteer.target._targetid.md b/new-docs/puppeteer.target._targetid.md deleted file mode 100644 index 2935253aa820d..0000000000000 --- a/new-docs/puppeteer.target._targetid.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_targetId](./puppeteer.target._targetid.md) - -## Target.\_targetId property - -Signature: - -```typescript -_targetId: string; -``` diff --git a/new-docs/puppeteer.target._targetinfo.md b/new-docs/puppeteer.target._targetinfo.md deleted file mode 100644 index ea43c2ac5e74e..0000000000000 --- a/new-docs/puppeteer.target._targetinfo.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_targetInfo](./puppeteer.target._targetinfo.md) - -## Target.\_targetInfo property - -Signature: - -```typescript -_targetInfo: Protocol.Target.TargetInfo; -``` diff --git a/new-docs/puppeteer.target._targetinfochanged.md b/new-docs/puppeteer.target._targetinfochanged.md deleted file mode 100644 index 8e15763f424ca..0000000000000 --- a/new-docs/puppeteer.target._targetinfochanged.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_targetInfoChanged](./puppeteer.target._targetinfochanged.md) - -## Target.\_targetInfoChanged() method - -Signature: - -```typescript -_targetInfoChanged(targetInfo: Protocol.Target.TargetInfo): void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| targetInfo | Protocol.Target.TargetInfo | | - -Returns: - -void - diff --git a/new-docs/puppeteer.target._workerpromise.md b/new-docs/puppeteer.target._workerpromise.md deleted file mode 100644 index d652fc5d48af9..0000000000000 --- a/new-docs/puppeteer.target._workerpromise.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Target](./puppeteer.target.md) > [\_workerPromise](./puppeteer.target._workerpromise.md) - -## Target.\_workerPromise property - -Signature: - -```typescript -_workerPromise?: Promise; -``` diff --git a/new-docs/puppeteer.target.browser.md b/new-docs/puppeteer.target.browser.md index 7d3bf11fc8001..2a9bcdef20514 100644 --- a/new-docs/puppeteer.target.browser.md +++ b/new-docs/puppeteer.target.browser.md @@ -4,6 +4,8 @@ ## Target.browser() method +Get the browser the target belongs to. + Signature: ```typescript diff --git a/new-docs/puppeteer.target.createcdpsession.md b/new-docs/puppeteer.target.createcdpsession.md index 2d262fa588a8b..25e6e5c6ebc95 100644 --- a/new-docs/puppeteer.target.createcdpsession.md +++ b/new-docs/puppeteer.target.createcdpsession.md @@ -4,6 +4,8 @@ ## Target.createCDPSession() method +Creates a Chrome Devtools Protocol session attached to the target. + Signature: ```typescript diff --git a/new-docs/puppeteer.target.md b/new-docs/puppeteer.target.md index 1c1f321b1ac57..18677447546cd 100644 --- a/new-docs/puppeteer.target.md +++ b/new-docs/puppeteer.target.md @@ -10,41 +10,20 @@ export declare class Target ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(targetInfo, browserContext, sessionFactory, ignoreHTTPSErrors, defaultViewport)](./puppeteer.target._constructor_.md) | | Constructs a new instance of the Target class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [\_browserContext](./puppeteer.target._browsercontext.md) | | [BrowserContext](./puppeteer.browsercontext.md) | | -| [\_closedCallback](./puppeteer.target._closedcallback.md) | | () => void | | -| [\_defaultViewport](./puppeteer.target._defaultviewport.md) | | Viewport | | -| [\_ignoreHTTPSErrors](./puppeteer.target._ignorehttpserrors.md) | | boolean | | -| [\_initializedCallback](./puppeteer.target._initializedcallback.md) | | (x: boolean) => void | | -| [\_initializedPromise](./puppeteer.target._initializedpromise.md) | | Promise<boolean> | | -| [\_isClosedPromise](./puppeteer.target._isclosedpromise.md) | | Promise<boolean> | | -| [\_isInitialized](./puppeteer.target._isinitialized.md) | | boolean | | -| [\_pagePromise](./puppeteer.target._pagepromise.md) | | Promise<[Page](./puppeteer.page.md)> | | -| [\_sessionFactory](./puppeteer.target._sessionfactory.md) | | () => Promise<[CDPSession](./puppeteer.cdpsession.md)> | | -| [\_targetId](./puppeteer.target._targetid.md) | | string | | -| [\_targetInfo](./puppeteer.target._targetinfo.md) | | Protocol.Target.TargetInfo | | -| [\_workerPromise](./puppeteer.target._workerpromise.md) | | Promise<[WebWorker](./puppeteer.webworker.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 `Target` class. ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [\_targetInfoChanged(targetInfo)](./puppeteer.target._targetinfochanged.md) | | | -| [browser()](./puppeteer.target.browser.md) | | | +| [browser()](./puppeteer.target.browser.md) | | Get the browser the target belongs to. | | [browserContext()](./puppeteer.target.browsercontext.md) | | | -| [createCDPSession()](./puppeteer.target.createcdpsession.md) | | | -| [opener()](./puppeteer.target.opener.md) | | | -| [page()](./puppeteer.target.page.md) | | | -| [type()](./puppeteer.target.type.md) | | | +| [createCDPSession()](./puppeteer.target.createcdpsession.md) | | Creates a Chrome Devtools Protocol session attached to the target. | +| [opener()](./puppeteer.target.opener.md) | | Get the target that opened this target. Top-level targets return null. | +| [page()](./puppeteer.target.page.md) | | If the target is not of type "page" or "background_page", returns null. | +| [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 "service_worker" or "shared_worker", returns null. | diff --git a/new-docs/puppeteer.target.opener.md b/new-docs/puppeteer.target.opener.md index 93f2eb03e3704..3d995f84b1f64 100644 --- a/new-docs/puppeteer.target.opener.md +++ b/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`. + Signature: ```typescript diff --git a/new-docs/puppeteer.target.page.md b/new-docs/puppeteer.target.page.md index bb8a37a628f6e..4a6fc642f11b5 100644 --- a/new-docs/puppeteer.target.page.md +++ b/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`. + Signature: ```typescript diff --git a/new-docs/puppeteer.target.type.md b/new-docs/puppeteer.target.type.md index e73fd0d48a6a2..5aab535d18847 100644 --- a/new-docs/puppeteer.target.type.md +++ b/new-docs/puppeteer.target.type.md @@ -4,6 +4,8 @@ ## Target.type() method +Identifies what kind of target this is. + Signature: ```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. + diff --git a/new-docs/puppeteer.target.worker.md b/new-docs/puppeteer.target.worker.md index 9906948160473..43f2777f7596f 100644 --- a/new-docs/puppeteer.target.worker.md +++ b/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`. + Signature: ```typescript diff --git a/src/common/Target.ts b/src/common/Target.ts index 1578fee3701e1..5a80e801494ba 100644 --- a/src/common/Target.ts +++ b/src/common/Target.ts @@ -23,20 +23,42 @@ import { Viewport } from './PuppeteerViewport'; import Protocol from '../protocol'; export class Target { - _targetInfo: Protocol.Target.TargetInfo; - _browserContext: BrowserContext; - _targetId: string; - _sessionFactory: () => Promise; - _ignoreHTTPSErrors: boolean; - _defaultViewport?: Viewport; - _pagePromise?: Promise; - _workerPromise?: Promise; + private _targetInfo: Protocol.Target.TargetInfo; + private _browserContext: BrowserContext; + + private _sessionFactory: () => Promise; + private _ignoreHTTPSErrors: boolean; + private _defaultViewport?: Viewport; + private _pagePromise?: Promise; + private _workerPromise?: Promise; + /** + * @internal + */ _initializedPromise: Promise; + /** + * @internal + */ _initializedCallback: (x: boolean) => void; + /** + * @internal + */ _isClosedPromise: Promise; + /** + * @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 { return this._sessionFactory(); } + /** + * If the target is not of type `"page"` or `"background_page"`, returns `null`. + */ async page(): Promise { 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 { 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;