From 9e0acebb75424168c8e241200061f3643f938a82 Mon Sep 17 00:00:00 2001 From: TASNEEM KOUSHAR Date: Wed, 26 May 2021 20:07:38 +0530 Subject: [PATCH] chore: add documentation for missing methods * fix: modified comment for method product, platform and newPage * fix: added comment for browsercontext, StartCSSCoverage, StartJSCoverage * fix: corrected comments for JSONValue, asElement, evaluateHandle * fix: corrected comments for JSONValue, asElement, evaluateHandle * fix: added comments for some of the method * fix: added proper comments Co-authored-by: Jack Franklin --- src/common/EventEmitter.ts | 4 ++-- src/common/HTTPRequest.ts | 7 +++++-- src/common/JSHandle.ts | 31 ++++++++++++++++++------------- src/common/Page.ts | 2 +- src/common/WebWorker.ts | 2 +- 5 files changed, 27 insertions(+), 19 deletions(-) diff --git a/src/common/EventEmitter.ts b/src/common/EventEmitter.ts index 0cc5e67fb13..91cf7e0904b 100644 --- a/src/common/EventEmitter.ts +++ b/src/common/EventEmitter.ts @@ -75,7 +75,7 @@ export class EventEmitter implements CommonEventEmitter { /** * Remove an event listener. - * @deprecated please use `off` instead. + * @deprecated please use {@link EventEmitter.off} instead. */ removeListener(event: EventType, handler: Handler): EventEmitter { this.off(event, handler); @@ -84,7 +84,7 @@ export class EventEmitter implements CommonEventEmitter { /** * Add an event listener. - * @deprecated please use `on` instead. + * @deprecated please use {@link EventEmitter.on} instead. */ addListener(event: EventType, handler: Handler): EventEmitter { this.on(event, handler); diff --git a/src/common/HTTPRequest.ts b/src/common/HTTPRequest.ts index 7b581ee936f..7c4dcd7ed9c 100644 --- a/src/common/HTTPRequest.ts +++ b/src/common/HTTPRequest.ts @@ -191,14 +191,16 @@ export class HTTPRequest { } /** - * @returns the response for this request, if a response has been received. + * @returns A matching `HTTPResponse` object, or null if the response has not + * been received yet. */ response(): HTTPResponse | null { return this._response; } /** - * @returns the frame that initiated the request. + * @returns the frame that initiated the request, or null if navigating to + * error pages. */ frame(): Frame | null { return this._frame; @@ -212,6 +214,7 @@ export class HTTPRequest { } /** + * A `redirectChain` is a chain of requests initiated to fetch a resource. * @remarks * * `redirectChain` is shared between all the requests of the same chain. diff --git a/src/common/JSHandle.ts b/src/common/JSHandle.ts index b731f52973a..db83587be5a 100644 --- a/src/common/JSHandle.ts +++ b/src/common/JSHandle.ts @@ -237,8 +237,8 @@ export class JSHandle { } /** - * Returns a JSON representation of the object. - * + * @returns Returns a JSON representation of the object.If the object has a + * `toJSON` function, it will not be called. * @remarks * * The JSON is generated by running {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify | JSON.stringify} @@ -259,12 +259,13 @@ export class JSHandle { } /** - * Returns either `null` or the object handle itself, if the object handle is - * an instance of {@link ElementHandle}. + * @returns Either `null` or the object handle itself, if the object + * handle is an instance of {@link ElementHandle}. */ asElement(): ElementHandle | null { - // This always returns null, but subclasses can override this and return an - // ElementHandle. + /* This always returns null, but subclasses can override this and return an + ElementHandle. + */ return null; } @@ -568,8 +569,10 @@ export class ElementHandle< `JSHandle#uploadFile can only be used in Node environments.` ); } - // This import is only needed for `uploadFile`, so keep it scoped here to avoid paying - // the cost unnecessarily. + /* + This import is only needed for `uploadFile`, so keep it scoped here to + avoid paying the cost unnecessarily. + */ const path = await import('path'); const fs = await helper.importFSModule(); // Locate all files and confirm that they exist. @@ -590,9 +593,10 @@ export class ElementHandle< const { node } = await this._client.send('DOM.describeNode', { objectId }); const { backendNodeId } = node; - // The zero-length array is a special case, it seems that DOM.setFileInputFiles does - // not actually update the files in that case, so the solution is to eval the element - // value to a new FileList directly. + /* The zero-length array is a special case, it seems that + DOM.setFileInputFiles does not actually update the files in that case, + so the solution is to eval the element value to a new FileList directly. + */ if (files.length === 0) { await (this as ElementHandle).evaluate((element) => { element.files = new DataTransfer().files; @@ -979,8 +983,9 @@ export interface PressOptions { } function computeQuadArea(quad: Array<{ x: number; y: number }>): number { - // Compute sum of all directed areas of adjacent triangles - // https://en.wikipedia.org/wiki/Polygon#Simple_polygons + /* Compute sum of all directed areas of adjacent triangles + https://en.wikipedia.org/wiki/Polygon#Simple_polygons + */ let area = 0; for (let i = 0; i < quad.length; ++i) { const p1 = quad[i]; diff --git a/src/common/Page.ts b/src/common/Page.ts index 22f6421ecf8..7119ce6759f 100644 --- a/src/common/Page.ts +++ b/src/common/Page.ts @@ -835,7 +835,7 @@ export class Page extends EventEmitter { * @remarks * Shortcut for {@link Frame.$ | Page.mainFrame().$(selector) }. * - * @param selector - A + * @param selector - A `selector` to query page for * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector} * to query page for. */ diff --git a/src/common/WebWorker.ts b/src/common/WebWorker.ts index 8a1c279fc47..8131e8a9efd 100644 --- a/src/common/WebWorker.ts +++ b/src/common/WebWorker.ts @@ -151,7 +151,7 @@ export class WebWorker extends EventEmitter { /** * The only difference between `worker.evaluate` and `worker.evaluateHandle` * is that `worker.evaluateHandle` returns in-page object (JSHandle). If the - * function passed to the `worker.evaluateHandle` returns a [Promise], then + * function passed to the `worker.evaluateHandle` returns a `Promise`, then * `worker.evaluateHandle` would wait for the promise to resolve and return * its value. Shortcut for * `await worker.executionContext()).evaluateHandle(pageFunction, ...args)`