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 <jacktfranklin@chromium.org>

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);

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.

src/common/JSHandle.ts

@@ -237,8 +237,8 @@ export class JSHandle<HandleObjectType = unknown> {
   }
 
   /**
-   * 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<HandleObjectType = unknown> {
   }
 
   /**
-   * 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<HTMLInputElement>).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];

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.
    */

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)`