From 41f23beb0da2433cf9103e5d8fc22a03b1820336 Mon Sep 17 00:00:00 2001 From: Ayman Azzam Date: Mon, 12 Apr 2021 15:57:05 +0200 Subject: [PATCH] docs: fix more tsdoc warnings * docs: fix most tsdoc warning messages * docs: i just added spaceline --- src/common/Browser.ts | 5 ++++- src/common/Connection.ts | 23 +++++++++++++++++------ src/common/ConnectionTransport.ts | 3 +++ src/common/Coverage.ts | 15 +++++++++++++-- src/common/DeviceDescriptors.ts | 14 ++++++++------ src/common/Errors.ts | 5 ++++- src/common/EventEmitter.ts | 5 +++++ src/common/ExecutionContext.ts | 2 +- src/common/LifecycleWatcher.ts | 6 +++++- src/common/Page.ts | 9 ++++++--- src/common/WebWorker.ts | 4 ++-- src/common/helper.ts | 3 +++ vendor/mitt/src/index.ts | 7 +++++++ 13 files changed, 78 insertions(+), 23 deletions(-) diff --git a/src/common/Browser.ts b/src/common/Browser.ts index 7e07dcaec31..5d1d1424004 100644 --- a/src/common/Browser.ts +++ b/src/common/Browser.ts @@ -24,7 +24,10 @@ import { Page } from './Page.js'; import { ChildProcess } from 'child_process'; import { Viewport } from './PuppeteerViewport.js'; -type BrowserCloseCallback = () => Promise | void; +/** + * @internal + */ +export type BrowserCloseCallback = () => Promise | void; const WEB_PERMISSION_TO_PROTOCOL_PERMISSION = new Map< Permission, diff --git a/src/common/Connection.ts b/src/common/Connection.ts index 300ab5b2518..4f11556a28a 100644 --- a/src/common/Connection.ts +++ b/src/common/Connection.ts @@ -23,7 +23,15 @@ import { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js'; import { ConnectionTransport } from './ConnectionTransport.js'; import { EventEmitter } from './EventEmitter.js'; -interface ConnectionCallback { +/** + * @public + */ +export { ConnectionTransport, ProtocolMapping }; + +/** + * @public + */ +export interface ConnectionCallback { resolve: Function; reject: Function; error: Error; @@ -67,8 +75,8 @@ export class Connection extends EventEmitter { } /** - * @param sessionId - - * @returns {?CDPSession} + * @param sessionId - The session id + * @returns The current CDP session if it exists */ session(sessionId: string): CDPSession | null { return this._sessions.get(sessionId) || null; @@ -167,8 +175,8 @@ export class Connection extends EventEmitter { } /** - * @param targetInfo - - * @returns {!Promise} + * @param targetInfo - The target info + * @returns The CDP session that is created */ async createSession( targetInfo: Protocol.Target.TargetInfo @@ -181,7 +189,10 @@ export class Connection extends EventEmitter { } } -interface CDPSessionOnMessageObject { +/** + * @public + */ +export interface CDPSessionOnMessageObject { id?: number; method: string; params: Record; diff --git a/src/common/ConnectionTransport.ts b/src/common/ConnectionTransport.ts index fc3deddb40c..dfeab2bd4f3 100644 --- a/src/common/ConnectionTransport.ts +++ b/src/common/ConnectionTransport.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export interface ConnectionTransport { send(string); close(); diff --git a/src/common/Coverage.ts b/src/common/Coverage.ts index 63060e656a8..c4910d45803 100644 --- a/src/common/Coverage.ts +++ b/src/common/Coverage.ts @@ -21,6 +21,11 @@ import { CDPSession } from './Connection.js'; import { EVALUATION_SCRIPT_URL } from './ExecutionContext.js'; +/** + * @internal + */ +export { PuppeteerEventListener }; + /** * The CoverageEntry class represents one entry of the coverage report. * @public @@ -164,7 +169,10 @@ export class Coverage { } } -class JSCoverage { +/** + * @public + */ +export class JSCoverage { _client: CDPSession; _enabled = false; _scriptURLs = new Map(); @@ -277,7 +285,10 @@ class JSCoverage { } } -class CSSCoverage { +/** + * @public + */ +export class CSSCoverage { _client: CDPSession; _enabled = false; _stylesheetURLs = new Map(); diff --git a/src/common/DeviceDescriptors.ts b/src/common/DeviceDescriptors.ts index 86459f3f065..783a947ae35 100644 --- a/src/common/DeviceDescriptors.ts +++ b/src/common/DeviceDescriptors.ts @@ -14,7 +14,10 @@ * limitations under the License. */ -interface Device { +/** + * @public + */ +export interface Device { name: string; userAgent: string; viewport: { @@ -1037,10 +1040,9 @@ export type DevicesMap = { [name: string]: Device; }; -const devicesMap: DevicesMap = {}; +/** + * @internal + */ +export const devicesMap: DevicesMap = {}; for (const device of devices) devicesMap[device.name] = device; -/** - * @public - */ -export { devicesMap }; diff --git a/src/common/Errors.ts b/src/common/Errors.ts index 277c747ed08..cbfd301ee93 100644 --- a/src/common/Errors.ts +++ b/src/common/Errors.ts @@ -14,7 +14,10 @@ * limitations under the License. */ -class CustomError extends Error { +/** + * @public + */ +export class CustomError extends Error { constructor(message: string) { super(message); this.name = this.constructor.name; diff --git a/src/common/EventEmitter.ts b/src/common/EventEmitter.ts index 92771f90553..e75377130f7 100644 --- a/src/common/EventEmitter.ts +++ b/src/common/EventEmitter.ts @@ -4,6 +4,11 @@ import mitt, { Handler, } from '../../vendor/mitt/src/index.js'; +/** + * @public + */ +export { EventType, Handler }; + /** * @public */ diff --git a/src/common/ExecutionContext.ts b/src/common/ExecutionContext.ts index 20ba954ab70..e8e2fbe4866 100644 --- a/src/common/ExecutionContext.ts +++ b/src/common/ExecutionContext.ts @@ -35,7 +35,7 @@ const SOURCE_URL_REGEX = /^[\040\t]*\/\/[@#] sourceURL=\s*(\S*?)\s*$/m; * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe | * frame } has "default" execution context that is always created after frame is * attached to DOM. This context is returned by the - * {@link frame.executionContext()} method. + * {@link Frame.executionContext} method. * - {@link https://developer.chrome.com/extensions | Extension}'s content scripts * create additional execution contexts. * diff --git a/src/common/LifecycleWatcher.ts b/src/common/LifecycleWatcher.ts index 1b611cd6063..6e45a442173 100644 --- a/src/common/LifecycleWatcher.ts +++ b/src/common/LifecycleWatcher.ts @@ -34,7 +34,11 @@ export type PuppeteerLifeCycleEvent = | 'domcontentloaded' | 'networkidle0' | 'networkidle2'; -type ProtocolLifeCycleEvent = + +/** + * @public + */ +export type ProtocolLifeCycleEvent = | 'load' | 'DOMContentLoaded' | 'networkIdle' diff --git a/src/common/Page.ts b/src/common/Page.ts index 38e9f900bd4..9a1eafc4987 100644 --- a/src/common/Page.ts +++ b/src/common/Page.ts @@ -130,7 +130,10 @@ export interface GeolocationOptions { accuracy?: number; } -interface MediaFeature { +/** + * @public + */ +export interface MediaFeature { name: string; value: string; } @@ -288,7 +291,7 @@ export const enum PageEmittedEvents { * Emitted when a page issues a request and contains a {@link HTTPRequest}. * * @remarks - * The object is readonly. See {@Page.setRequestInterception} for intercepting + * The object is readonly. See {@link Page.setRequestInterception} for intercepting * and mutating requests. */ Request = 'request', @@ -297,7 +300,7 @@ export const enum PageEmittedEvents { * * @remarks * For certain requests, might contain undefined. - * @see https://crbug.com/750469 + * {@link https://crbug.com/750469} */ RequestServedFromCache = 'requestservedfromcache', /** diff --git a/src/common/WebWorker.ts b/src/common/WebWorker.ts index a4d415315e4..87fb307bab5 100644 --- a/src/common/WebWorker.ts +++ b/src/common/WebWorker.ts @@ -24,7 +24,7 @@ import { EvaluateHandleFn, SerializableOrJSHandle } from './EvalTypes.js'; /** * @internal */ -type ConsoleAPICalledCallback = ( +export type ConsoleAPICalledCallback = ( eventType: string, handles: JSHandle[], trace: Protocol.Runtime.StackTrace @@ -33,7 +33,7 @@ type ConsoleAPICalledCallback = ( /** * @internal */ -type ExceptionThrownCallback = ( +export type ExceptionThrownCallback = ( details: Protocol.Runtime.ExceptionDetails ) => void; type JSHandleFactory = (obj: Protocol.Runtime.RemoteObject) => JSHandle; diff --git a/src/common/helper.ts b/src/common/helper.ts index ba2af396a87..122fa135bc9 100644 --- a/src/common/helper.ts +++ b/src/common/helper.ts @@ -86,6 +86,9 @@ async function releaseObject( }); } +/** + * @public + */ export interface PuppeteerEventListener { emitter: CommonEventEmitter; eventName: string | symbol; diff --git a/vendor/mitt/src/index.ts b/vendor/mitt/src/index.ts index ae85607f7cf..7b5342f09e1 100644 --- a/vendor/mitt/src/index.ts +++ b/vendor/mitt/src/index.ts @@ -1,7 +1,14 @@ + +/** + * @public + */ export type EventType = string | symbol; // An event handler can take an optional event argument // and should not return a value +/** + * @public + */ export type Handler = (event?: T) => void; export type WildcardHandler = (type: EventType, event?: any) => void;