From a46c78fc918579e215794da4316b5c38ed7d7e2f Mon Sep 17 00:00:00 2001 From: Martin Splitt Date: Wed, 24 Jun 2020 14:57:59 +0200 Subject: [PATCH] docs(new): Adds TSDoc to Tracing class (#6088) * Adds tsdoc to Tracing class * Updates tsdocs Co-authored-by: martinsplitt --- new-docs/puppeteer.md | 2 +- new-docs/puppeteer.tracing._constructor_.md | 20 ---------------- new-docs/puppeteer.tracing.md | 24 ++++++++++++++----- new-docs/puppeteer.tracing.start.md | 8 ++++++- new-docs/puppeteer.tracing.stop.md | 4 ++++ src/common/Tracing.ts | 26 +++++++++++++++++++++ 6 files changed, 56 insertions(+), 28 deletions(-) delete mode 100644 new-docs/puppeteer.tracing._constructor_.md diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 3bba9f2407505..e201778516537 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -34,7 +34,7 @@ | [Target](./puppeteer.target.md) | | | [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | | [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | -| [Tracing](./puppeteer.tracing.md) | | +| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | | [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | ## Enumerations diff --git a/new-docs/puppeteer.tracing._constructor_.md b/new-docs/puppeteer.tracing._constructor_.md deleted file mode 100644 index 7c13c17217bea..0000000000000 --- a/new-docs/puppeteer.tracing._constructor_.md +++ /dev/null @@ -1,20 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Tracing](./puppeteer.tracing.md) > [(constructor)](./puppeteer.tracing._constructor_.md) - -## Tracing.(constructor) - -Constructs a new instance of the `Tracing` class - -Signature: - -```typescript -constructor(client: CDPSession); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | - diff --git a/new-docs/puppeteer.tracing.md b/new-docs/puppeteer.tracing.md index c83c3a8d3783a..d76c2313df4df 100644 --- a/new-docs/puppeteer.tracing.md +++ b/new-docs/puppeteer.tracing.md @@ -4,17 +4,29 @@ ## Tracing class +The Tracing class exposes the tracing audit interface. + Signature: ```typescript export declare class Tracing ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client)](./puppeteer.tracing._constructor_.md) | | Constructs a new instance of the Tracing class | +You can use `tracing.start` and `tracing.stop` to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/). + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Tracing` class. + +## Example + + +```js +await page.tracing.start({path: 'trace.json'}); +await page.goto('https://www.google.com'); +await page.tracing.stop(); + +``` ## Properties @@ -28,6 +40,6 @@ export declare class Tracing | Method | Modifiers | Description | | --- | --- | --- | -| [start(options)](./puppeteer.tracing.start.md) | | | -| [stop()](./puppeteer.tracing.stop.md) | | | +| [start(options)](./puppeteer.tracing.start.md) | | Starts a trace for the current page. | +| [stop()](./puppeteer.tracing.stop.md) | | Stops a trace started with the start method. | diff --git a/new-docs/puppeteer.tracing.start.md b/new-docs/puppeteer.tracing.start.md index 976b44b305f92..5765163397440 100644 --- a/new-docs/puppeteer.tracing.start.md +++ b/new-docs/puppeteer.tracing.start.md @@ -4,6 +4,8 @@ ## Tracing.start() method +Starts a trace for the current page. + Signature: ```typescript @@ -14,9 +16,13 @@ start(options?: TracingOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | TracingOptions | | +| options | TracingOptions | Optional TracingOptions. | Returns: Promise<void> +## Remarks + +Only one trace can be active at a time per browser. + diff --git a/new-docs/puppeteer.tracing.stop.md b/new-docs/puppeteer.tracing.stop.md index a14c9d6e76044..bb59ede6a6324 100644 --- a/new-docs/puppeteer.tracing.stop.md +++ b/new-docs/puppeteer.tracing.stop.md @@ -4,6 +4,8 @@ ## Tracing.stop() method +Stops a trace started with the `start` method. + Signature: ```typescript @@ -13,3 +15,5 @@ stop(): Promise; Promise<Buffer> +Promise which resolves to buffer with trace data. + diff --git a/src/common/Tracing.ts b/src/common/Tracing.ts index 5f2c4a4880a88..673310dd1dfeb 100644 --- a/src/common/Tracing.ts +++ b/src/common/Tracing.ts @@ -23,15 +23,37 @@ interface TracingOptions { categories?: string[]; } +/** + * The Tracing class exposes the tracing audit interface. + * @remarks + * You can use `tracing.start` and `tracing.stop` to create a trace file + * which can be opened in Chrome DevTools or {@link https://chromedevtools.github.io/timeline-viewer/ | timeline viewer}. + * + * @example + * ```js + * await page.tracing.start({path: 'trace.json'}); + * await page.goto('https://www.google.com'); + * await page.tracing.stop(); + * ``` + */ export class Tracing { _client: CDPSession; _recording = false; _path = ''; + /** + * @internal + */ constructor(client: CDPSession) { this._client = client; } + /** + * Starts a trace for the current page. + * @remarks + * Only one trace can be active at a time per browser. + * @param options - Optional `TracingOptions`. + */ async start(options: TracingOptions = {}): Promise { assert( !this._recording, @@ -68,6 +90,10 @@ export class Tracing { }); } + /** + * Stops a trace started with the `start` method. + * @returns Promise which resolves to buffer with trace data. + */ async stop(): Promise { let fulfill: (value: Buffer) => void; const contentPromise = new Promise((x) => (fulfill = x));