docs(new): Adds TSDoc to Mouse class (#6086)

* Adds tsdoc to Mouse class

* Updates puppeteer class tsdoc

* docs(new): add TSDoc comments to BrowserFetcher (#6078)

* Adds tsdoc for Touchscreen (#6087)

Co-authored-by: martinsplitt <martin@geekonaut.de>

* Adds tsdoc to Mouse class

* Fixes tsdoc comment for Mouse class

Co-authored-by: martinsplitt <martin@geekonaut.de>

new-docs/puppeteer.md

@@ -27,7 +27,7 @@
 |  [HTTPResponse](./puppeteer.httpresponse.md) |  |
 |  [JSHandle](./puppeteer.jshandle.md) |  |
 |  [Keyboard](./puppeteer.keyboard.md) |  |
-|  [Mouse](./puppeteer.mouse.md) |  |
+|  [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. |
 |  [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. |
 |  [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class |
 |  [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. |

new-docs/puppeteer.mouse._constructor_.md

@@ -1,21 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Mouse](./puppeteer.mouse.md) &gt; [(constructor)](./puppeteer.mouse._constructor_.md)
-
-## Mouse.(constructor)
-
-Constructs a new instance of the `Mouse` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(client: CDPSession, keyboard: Keyboard);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  client | [CDPSession](./puppeteer.cdpsession.md) |  |
-|  keyboard | [Keyboard](./puppeteer.keyboard.md) |  |
-

new-docs/puppeteer.mouse.click.md

@@ -4,6 +4,8 @@
 
 ## Mouse.click() method
 
+Shortcut for `mouse.move`<!-- -->, `mouse.down` and `mouse.up`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -16,9 +18,9 @@ click(x: number, y: number, options?: MouseOptions & {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  x | number |  |
+|  x | number | Horizontal position of the mouse. |
-|  y | number |  |
+|  y | number | Vertical position of the mouse. |
-|  options | MouseOptions &amp; { delay?: number; } |  |
+|  options | MouseOptions &amp; { delay?: number; } | Optional <code>MouseOptions</code>. |
 
 <b>Returns:</b>
 

new-docs/puppeteer.mouse.down.md

@@ -4,6 +4,8 @@
 
 ## Mouse.down() method
 
+Dispatches a `mousedown` event.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,7 +16,7 @@ down(options?: MouseOptions): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | MouseOptions |  |
+|  options | MouseOptions | Optional <code>MouseOptions</code>. |
 
 <b>Returns:</b>
 

new-docs/puppeteer.mouse.md

@@ -4,17 +4,74 @@
 
 ## Mouse class
 
+The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class Mouse 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+Every `page` object has its own Mouse, accessible with \[`page.mouse`<!-- -->\](\#pagemouse).
-|  --- | --- | --- |
+
-|  [(constructor)(client, keyboard)](./puppeteer.mouse._constructor_.md) |  | Constructs a new instance of the <code>Mouse</code> class |
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Mouse` class.
+
+## Example 1
+
+
+```js
+// Using ‘page.mouse’ to trace a 100x100 square.
+await page.mouse.move(0, 0);
+await page.mouse.down();
+await page.mouse.move(0, 100);
+await page.mouse.move(100, 100);
+await page.mouse.move(100, 0);
+await page.mouse.move(0, 0);
+await page.mouse.up();
+
+```
+\*\*Note\*\*: The mouse events trigger synthetic `MouseEvent`<!-- -->s. This means that it does not fully replicate the functionality of what a normal user would be able to do with their mouse.
+
+For example, dragging and selecting text is not possible using `page.mouse`<!-- -->. Instead, you can use the [\`DocumentOrShadowRoot.getSelection()\`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection) functionality implemented in the platform.
+
+## Example 2
+
+For example, if you want to select all content between nodes:
+
+```js
+await page.evaluate((from, to) => {
+  const selection = from.getRootNode().getSelection();
+  const range = document.createRange();
+  range.setStartBefore(from);
+  range.setEndAfter(to);
+  selection.removeAllRanges();
+  selection.addRange(range);
+}, fromJSHandle, toJSHandle);
+
+```
+If you then would want to copy-paste your selection, you can use the clipboard api:
+
+```js
+// The clipboard api does not allow you to copy, unless the tab is focused.
+await page.bringToFront();
+await page.evaluate(() => {
+  // Copy the selected content to the clipboard
+  document.execCommand('copy');
+  // Obtain the content of the clipboard as a string
+  return navigator.clipboard.readText();
+});
+
+```
+\*\*Note\*\*: If you want access to the clipboard API, you have to give it permission to do so:
+
+```js
+await browser.defaultBrowserContext().overridePermissions(
+  '<your origin>', ['clipboard-read', 'clipboard-write']
+);
+
+```
 
 ## Properties
 
@@ -30,8 +87,8 @@ export declare class Mouse
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [click(x, y, options)](./puppeteer.mouse.click.md) |  |  |
+|  [click(x, y, options)](./puppeteer.mouse.click.md) |  | Shortcut for <code>mouse.move</code>, <code>mouse.down</code> and <code>mouse.up</code>. |
-|  [down(options)](./puppeteer.mouse.down.md) |  |  |
+|  [down(options)](./puppeteer.mouse.down.md) |  | Dispatches a <code>mousedown</code> event. |
-|  [move(x, y, options)](./puppeteer.mouse.move.md) |  |  |
+|  [move(x, y, options)](./puppeteer.mouse.move.md) |  | Dispatches a <code>mousemove</code> event. |
-|  [up(options)](./puppeteer.mouse.up.md) |  |  |
+|  [up(options)](./puppeteer.mouse.up.md) |  | Dispatches a <code>mouseup</code> event. |
 

new-docs/puppeteer.mouse.move.md

@@ -4,6 +4,8 @@
 
 ## Mouse.move() method
 
+Dispatches a `mousemove` event.
+
 <b>Signature:</b>
 
 ```typescript
@@ -16,9 +18,9 @@ move(x: number, y: number, options?: {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  x | number |  |
+|  x | number | Horizontal position of the mouse. |
-|  y | number |  |
+|  y | number | Vertical position of the mouse. |
-|  options | { steps?: number; } |  |
+|  options | { steps?: number; } | Optional object. If specified, the <code>steps</code> property sends intermediate <code>mousemove</code> events when set to <code>1</code> (default). |
 
 <b>Returns:</b>
 

new-docs/puppeteer.mouse.up.md

@@ -4,6 +4,8 @@
 
 ## Mouse.up() method
 
+Dispatches a `mouseup` event.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,7 +16,7 @@ up(options?: MouseOptions): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | MouseOptions |  |
+|  options | MouseOptions | Optional <code>MouseOptions</code>. |
 
 <b>Returns:</b>
 

src/common/Input.ts

@@ -153,6 +153,63 @@ interface MouseOptions {
   clickCount?: number;
 }
 
+/**
+ * The Mouse class operates in main-frame CSS pixels
+ * relative to the top-left corner of the viewport.
+ * @remarks
+ * Every `page` object has its own Mouse, accessible with [`page.mouse`](#pagemouse).
+ *
+ * @example
+ * ```js
+ * // Using ‘page.mouse’ to trace a 100x100 square.
+ * await page.mouse.move(0, 0);
+ * await page.mouse.down();
+ * await page.mouse.move(0, 100);
+ * await page.mouse.move(100, 100);
+ * await page.mouse.move(100, 0);
+ * await page.mouse.move(0, 0);
+ * await page.mouse.up();
+ * ```
+ *
+ * **Note**: The mouse events trigger synthetic `MouseEvent`s.
+ * This means that it does not fully replicate the functionality of what a normal user
+ * would be able to do with their mouse.
+ *
+ * For example, dragging and selecting text is not possible using `page.mouse`.
+ * Instead, you can use the {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection | `DocumentOrShadowRoot.getSelection()`} functionality implemented in the platform.
+ *
+ * @example
+ * For example, if you want to select all content between nodes:
+ * ```js
+ * await page.evaluate((from, to) => {
+ *   const selection = from.getRootNode().getSelection();
+ *   const range = document.createRange();
+ *   range.setStartBefore(from);
+ *   range.setEndAfter(to);
+ *   selection.removeAllRanges();
+ *   selection.addRange(range);
+ * }, fromJSHandle, toJSHandle);
+ * ```
+ * If you then would want to copy-paste your selection, you can use the clipboard api:
+ * ```js
+ * // The clipboard api does not allow you to copy, unless the tab is focused.
+ * await page.bringToFront();
+ * await page.evaluate(() => {
+ *   // Copy the selected content to the clipboard
+ *   document.execCommand('copy');
+ *   // Obtain the content of the clipboard as a string
+ *   return navigator.clipboard.readText();
+ * });
+ * ```
+ * **Note**: If you want access to the clipboard API,
+ * you have to give it permission to do so:
+ * ```js
+ * await browser.defaultBrowserContext().overridePermissions(
+ *   '<your origin>', ['clipboard-read', 'clipboard-write']
+ * );
+ * ```
+ * @public
+ */
 export class Mouse {
   _client: CDPSession;
   _keyboard: Keyboard;
@@ -160,14 +217,20 @@ export class Mouse {
   _y = 0;
   _button: MouseButton = 'none';
   /**
-   * @param {CDPSession} client
+   * @internal
-   * @param {!Keyboard} keyboard
    */
   constructor(client: CDPSession, keyboard: Keyboard) {
     this._client = client;
     this._keyboard = keyboard;
   }
 
+  /**
+   * Dispatches a `mousemove` event.
+   * @param x - Horizontal position of the mouse.
+   * @param y - Vertical position of the mouse.
+   * @param options - Optional object. If specified, the `steps` property
+   * sends intermediate `mousemove` events when set to `1` (default).
+   */
   async move(
     x: number,
     y: number,
@@ -189,6 +252,12 @@ export class Mouse {
     }
   }
 
+  /**
+   * Shortcut for `mouse.move`, `mouse.down` and `mouse.up`.
+   * @param x - Horizontal position of the mouse.
+   * @param y - Vertical position of the mouse.
+   * @param options - Optional `MouseOptions`.
+   */
   async click(
     x: number,
     y: number,
@@ -208,6 +277,10 @@ export class Mouse {
     }
   }
 
+  /**
+   * Dispatches a `mousedown` event.
+   * @param options - Optional `MouseOptions`.
+   */
   async down(options: MouseOptions = {}): Promise<void> {
     const { button = 'left', clickCount = 1 } = options;
     this._button = button;
@@ -222,7 +295,8 @@ export class Mouse {
   }
 
   /**
-   * @param {!{button?: "left"|"right"|"middle", clickCount?: number}=} options
+   * Dispatches a `mouseup` event.
+   * @param options - Optional `MouseOptions`.
    */
   async up(options: MouseOptions = {}): Promise<void> {
     const { button = 'left', clickCount = 1 } = options;