From e2e050259f9749fad676b4ea5c78f748db8f6bcb Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 6 Jul 2020 12:37:16 +0100 Subject: [PATCH] chore(docs): fix DOMWorld doc warnings (#6166) I noticed that DOMWorld was spitting a lot of warnings out when we generated the docs. It was mostly easy tidy-ups and removing old JSDoc comments and now the warnings are gone :) --- new-docs/puppeteer.frame.goto.md | 2 +- new-docs/puppeteer.frame.setcontent.md | 2 +- new-docs/puppeteer.frame.waitfornavigation.md | 2 +- new-docs/puppeteer.md | 1 + new-docs/puppeteer.puppeteerlifecycleevent.md | 11 +++++ new-docs/puppeteer.waitforoptions.md | 2 +- src/api-docs-entry.ts | 2 + src/common/DOMWorld.ts | 46 ++++--------------- src/common/LifecycleWatcher.ts | 3 ++ src/common/TimeoutSettings.ts | 6 +-- 10 files changed, 34 insertions(+), 43 deletions(-) create mode 100644 new-docs/puppeteer.puppeteerlifecycleevent.md diff --git a/new-docs/puppeteer.frame.goto.md b/new-docs/puppeteer.frame.goto.md index 2395e11156865..1aa74033a942e 100644 --- a/new-docs/puppeteer.frame.goto.md +++ b/new-docs/puppeteer.frame.goto.md @@ -19,7 +19,7 @@ goto(url: string, options?: { | Parameter | Type | Description | | --- | --- | --- | | url | string | | -| options | { referer?: string; timeout?: number; waitUntil?: PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\]; } | | +| options | { referer?: string; timeout?: number; waitUntil?: [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)\[\]; } | | Returns: diff --git a/new-docs/puppeteer.frame.setcontent.md b/new-docs/puppeteer.frame.setcontent.md index c4ff93e6fc0e2..2535e79f73519 100644 --- a/new-docs/puppeteer.frame.setcontent.md +++ b/new-docs/puppeteer.frame.setcontent.md @@ -18,7 +18,7 @@ setContent(html: string, options?: { | Parameter | Type | Description | | --- | --- | --- | | html | string | | -| options | { timeout?: number; waitUntil?: PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\]; } | | +| options | { timeout?: number; waitUntil?: [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)\[\]; } | | Returns: diff --git a/new-docs/puppeteer.frame.waitfornavigation.md b/new-docs/puppeteer.frame.waitfornavigation.md index 05035d7ca5a77..bdc3a997ad7b5 100644 --- a/new-docs/puppeteer.frame.waitfornavigation.md +++ b/new-docs/puppeteer.frame.waitfornavigation.md @@ -17,7 +17,7 @@ waitForNavigation(options?: { | Parameter | Type | Description | | --- | --- | --- | -| options | { timeout?: number; waitUntil?: PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\]; } | | +| options | { timeout?: number; waitUntil?: [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)\[\]; } | | Returns: diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 995743543293f..c296a75ea1099 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -102,6 +102,7 @@ | [Platform](./puppeteer.platform.md) | Supported platforms. | | [Product](./puppeteer.product.md) | Supported products. | | [PuppeteerErrors](./puppeteer.puppeteererrors.md) | | +| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) | | | [Serializable](./puppeteer.serializable.md) | | | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md) | | | [UnwrapElementHandle](./puppeteer.unwrapelementhandle.md) | Unwraps a DOM element out of an ElementHandle instance | diff --git a/new-docs/puppeteer.puppeteerlifecycleevent.md b/new-docs/puppeteer.puppeteerlifecycleevent.md new file mode 100644 index 0000000000000..7157d55c822df --- /dev/null +++ b/new-docs/puppeteer.puppeteerlifecycleevent.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) + +## PuppeteerLifeCycleEvent type + +Signature: + +```typescript +export declare type PuppeteerLifeCycleEvent = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'; +``` diff --git a/new-docs/puppeteer.waitforoptions.md b/new-docs/puppeteer.waitforoptions.md index 75c6b9da6d5a9..c87f1b9b59943 100644 --- a/new-docs/puppeteer.waitforoptions.md +++ b/new-docs/puppeteer.waitforoptions.md @@ -16,5 +16,5 @@ export interface WaitForOptions | Property | Type | Description | | --- | --- | --- | | [timeout](./puppeteer.waitforoptions.timeout.md) | number | Maximum wait time in milliseconds, defaults to 30 seconds, pass 0 to disable the timeout. | -| [waitUntil](./puppeteer.waitforoptions.waituntil.md) | PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\] | | +| [waitUntil](./puppeteer.waitforoptions.waituntil.md) | [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md) \| [PuppeteerLifeCycleEvent](./puppeteer.puppeteerlifecycleevent.md)\[\] | | diff --git a/src/api-docs-entry.ts b/src/api-docs-entry.ts index b7dcf04be0287..359c3989ed6d4 100644 --- a/src/api-docs-entry.ts +++ b/src/api-docs-entry.ts @@ -54,3 +54,5 @@ export * from './common/NetworkManager'; export * from './common/WebWorker'; export * from './common/USKeyboardLayout'; export * from './common/EvalTypes'; +export * from './common/TimeoutSettings'; +export * from './common/LifecycleWatcher'; diff --git a/src/common/DOMWorld.ts b/src/common/DOMWorld.ts index f5c075ec33583..933ceef6db5a8 100644 --- a/src/common/DOMWorld.ts +++ b/src/common/DOMWorld.ts @@ -48,15 +48,18 @@ export interface WaitForSelectorOptions { * @internal */ export class DOMWorld { - _frameManager: FrameManager; - _frame: Frame; - _timeoutSettings: TimeoutSettings; - _documentPromise?: Promise = null; - _contextPromise?: Promise = null; + private _frameManager: FrameManager; + private _frame: Frame; + private _timeoutSettings: TimeoutSettings; + private _documentPromise?: Promise = null; + private _contextPromise?: Promise = null; - _contextResolveCallback?: (x?: ExecutionContext) => void = null; + private _contextResolveCallback?: (x?: ExecutionContext) => void = null; - _detached = false; + private _detached = false; + /** + * internal + */ _waitTasks = new Set(); constructor( @@ -74,9 +77,6 @@ export class DOMWorld { return this._frame; } - /** - * @param {?ExecutionContext} context - */ _setContext(context?: ExecutionContext): void { if (context) { this._contextResolveCallback.call(null, context); @@ -102,9 +102,6 @@ export class DOMWorld { ); } - /** - * @returns {!Promise} - */ executionContext(): Promise { if (this._detached) throw new Error( @@ -121,11 +118,6 @@ export class DOMWorld { return context.evaluateHandle(pageFunction, ...args); } - /** - * @param {Function|string} pageFunction - * @param {!Array<*>} args - * @returns {!Promise<*>} - */ async evaluate( pageFunction: Function | string, ...args: unknown[] @@ -134,10 +126,6 @@ export class DOMWorld { return context.evaluate(pageFunction, ...args); } - /** - * @param {string} selector - * @returns {!Promise} - */ async $(selector: string): Promise { const document = await this._document(); const value = await document.$(selector); @@ -188,10 +176,6 @@ export class DOMWorld { return value; } - /** - * @param {string} selector - * @returns {!Promise>} - */ async $$(selector: string): Promise { const document = await this._document(); const value = await document.$$(selector); @@ -249,8 +233,6 @@ export class DOMWorld { * You can pass a URL, filepath or string of contents. Note that when running Puppeteer * in a browser environment you cannot pass a filepath and should use either * `url` or `content`. - * - * @param options */ async addScriptTag(options: { url?: string; @@ -340,7 +322,6 @@ export class DOMWorld { * in a browser environment you cannot pass a filepath and should use either * `url` or `content`. * - * @param options */ async addStyleTag(options: { url?: string; @@ -541,13 +522,6 @@ export class DOMWorld { } return handle.asElement(); - /** - * @param {string} selectorOrXPath - * @param {boolean} isXPath - * @param {boolean} waitForVisible - * @param {boolean} waitForHidden - * @returns {?Node|boolean} - */ function predicate( selectorOrXPath: string, isXPath: boolean, diff --git a/src/common/LifecycleWatcher.ts b/src/common/LifecycleWatcher.ts index 7f400911f1ee4..52eb995dd14c4 100644 --- a/src/common/LifecycleWatcher.ts +++ b/src/common/LifecycleWatcher.ts @@ -43,6 +43,9 @@ const puppeteerToProtocolLifecycle = new Map< ['networkidle2', 'networkAlmostIdle'], ]); +/** + * @internal + */ export class LifecycleWatcher { _expectedLifecycle: ProtocolLifeCycleEvent[]; _frameManager: FrameManager; diff --git a/src/common/TimeoutSettings.ts b/src/common/TimeoutSettings.ts index bb07751f92aff..9c441498de45e 100644 --- a/src/common/TimeoutSettings.ts +++ b/src/common/TimeoutSettings.ts @@ -16,6 +16,9 @@ const DEFAULT_TIMEOUT = 30000; +/** + * @internal + */ export class TimeoutSettings { _defaultTimeout: number | null; _defaultNavigationTimeout: number | null; @@ -29,9 +32,6 @@ export class TimeoutSettings { this._defaultTimeout = timeout; } - /** - * @param {number} timeout - */ setDefaultNavigationTimeout(timeout: number): void { this._defaultNavigationTimeout = timeout; }