From 1108b63d82c145e1d86b7d722f27070c1ba2a29b Mon Sep 17 00:00:00 2001
From: TASNEEM KOUSHAR <imatasneemkoushar@gmail.com>
Date: Wed, 2 Jun 2021 18:17:20 +0530
Subject: [PATCH] chore(docs): add comments to page.ts

* 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

* fix: added comment for some methods in page.ts

* fix: rectified the comments

* fix: changed some of the comments

Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
---
 src/common/Page.ts | 62 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/src/common/Page.ts b/src/common/Page.ts
index 7119ce6759f..4a2ecae2d63 100644
--- a/src/common/Page.ts
+++ b/src/common/Page.ts
@@ -694,14 +694,14 @@ export class Page extends EventEmitter {
   }
 
   /**
-   * @returns The browser this page belongs to.
+   * Get the browser the page belongs to.
    */
   browser(): Browser {
     return this._target.browser();
   }
 
   /**
-   * @returns The browser context that the page belongs to
+   * Get the browser context that the page belongs to.
    */
   browserContext(): BrowserContext {
     return this._target.browserContext();
@@ -1085,12 +1085,27 @@ export class Page extends EventEmitter {
     return this.mainFrame().$$eval<ReturnType>(selector, pageFunction, ...args);
   }
 
+  /**
+   * The method runs `document.querySelectorAll` within the page. If no elements
+   * match the selector, the return value resolves to `[]`.
+   * @remarks
+   * Shortcut for {@link Frame.$$ | Page.mainFrame().$$(selector) }.
+   * @param selector - A `selector` to query page for
+   */
   async $$<T extends Element = Element>(
     selector: string
   ): Promise<Array<ElementHandle<T>>> {
     return this.mainFrame().$$<T>(selector);
   }
 
+  /**
+   * The method evaluates the XPath expression relative to the page document as
+   * its context node. If there are no such elements, the method resolves to an
+   * empty array.
+   * @remarks
+   * Shortcut for {@link Frame.$x | Page.mainFrame().$x(expression) }.
+   * @param expression - Expression to evaluate
+   */
   async $x(expression: string): Promise<ElementHandle[]> {
     return this.mainFrame().$x(expression);
   }
@@ -1148,6 +1163,13 @@ export class Page extends EventEmitter {
       await this._client.send('Network.setCookies', { cookies: items });
   }
 
+  /**
+   * Adds a `<script>` tag into the page with the desired URL or content.
+   * @remarks
+   * Shortcut for {@link Frame.addScriptTag | page.mainFrame().addScriptTag(options) }.
+   * @returns Promise which resolves to the added tag when the script's onload fires or
+   * when the script content was injected into frame.
+   */
   async addScriptTag(options: {
     url?: string;
     path?: string;
@@ -1157,6 +1179,12 @@ export class Page extends EventEmitter {
     return this.mainFrame().addScriptTag(options);
   }
 
+  /**
+   * Adds a `<link rel="stylesheet">` tag into the page with the desired URL or a
+   * `<style type="text/css">` tag with the content.
+   * @returns Promise which resolves to the added tag when the stylesheet's
+   * onload fires or when the CSS content was injected into frame.
+   */
   async addStyleTag(options: {
     url?: string;
     path?: string;
@@ -1185,6 +1213,10 @@ export class Page extends EventEmitter {
     );
   }
 
+  /**
+   * Provide credentials for `HTTP authentication`.
+   * @remarks To disable authentication, pass `null`.
+   */
   async authenticate(credentials: Credentials): Promise<void> {
     return this._frameManager.networkManager().authenticate(credentials);
   }
@@ -1475,6 +1507,9 @@ export class Page extends EventEmitter {
     return result[0];
   }
 
+  /**
+   * Brings page to front (activates tab).
+   */
   async bringToFront(): Promise<void> {
     await this._client.send('Page.bringToFront');
   }
@@ -1994,6 +2029,29 @@ export class Page extends EventEmitter {
     return this._mouse;
   }
 
+  /**
+   * This method fetches an element with `selector`, scrolls it into view if
+   * needed, and then uses {@link page.mouse} to click in the center of the
+   * element. If there's no element matching `selector`, the method throws an
+   * error.
+   * @remarks Bear in mind that if `click()` triggers a navigation event and
+   * there's a separate `page.waitForNavigation()` promise to be resolved, you
+   * may end up with a race condition that yields unexpected results. The
+   * correct pattern for click and wait for navigation is the following:
+   * ```js
+   * const [response] = await Promise.all([
+   * page.waitForNavigation(waitOptions),
+   * page.click(selector, clickOptions),
+   * ]);
+   * ```
+   * Shortcut for {@link Frame.click | page.mainFrame().click(selector[, options]) }.
+   * @param selector - A `selector` to search for element to click. If there are
+   * multiple elements satisfying the `selector`, the first will be clicked
+   * @param options - `Object`
+   * @returns Promise which resolves when the element matching `selector` is
+   * successfully clicked. The Promise will be rejected if there is no element
+   * matching `selector`.
+   */
   click(
     selector: string,
     options: {