docs(new): add TSDoc comments to Keyboard (#6099)

Co-authored-by: Tim van der Lippe <tvanderlippe@google.com>

new-docs/puppeteer.keyboard.down.md

@@ -4,6 +4,8 @@
 
 ## Keyboard.down() method
 
+Dispatches a `keydown` event.
+
 <b>Signature:</b>
 
 ```typescript
@@ -16,10 +18,18 @@ down(key: KeyInput, options?: {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  key | [KeyInput](./puppeteer.keyinput.md) |  |
-|  options | { text?: string; } |  |
+|  key | [KeyInput](./puppeteer.keyinput.md) | Name of key to press, such as <code>ArrowLeft</code>. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. |
+|  options | { text?: string; } | An object of options. Accepts text which, if specified, generates an input event with this text. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`<!-- -->/`input` event will also generated. The `text` option can be specified to force an input event to be generated. If `key` is a modifier key, `Shift`<!-- -->, `Meta`<!-- -->, `Control`<!-- -->, or `Alt`<!-- -->, subsequent key presses will be sent with that modifier active. To release the modifier key, use [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->.
+
+After the key is pressed once, subsequent calls to [Keyboard.down()](./puppeteer.keyboard.down.md) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->.
+
+Modifier keys DO influence [Keyboard.down()](./puppeteer.keyboard.down.md)<!-- -->. Holding down `Shift` will type the text in upper case.
+

new-docs/puppeteer.keyboard.md

@@ -4,33 +4,58 @@
 
 ## Keyboard class
 
+Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md)<!-- -->, which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class Keyboard 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(client)](./puppeteer.keyboard._constructor_.md) |  | Constructs a new instance of the <code>Keyboard</code> class |
+For finer control, you can use [Keyboard.down()](./puppeteer.keyboard.down.md)<!-- -->, [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->, and [Keyboard.sendCharacter()](./puppeteer.keyboard.sendcharacter.md) to manually fire events as if they were generated from a real keyboard.
+
+On MacOS, keyboard shortcuts like `⌘ A` -<!-- -->&gt; Select All do not work. See [\#1313](https://github.com/puppeteer/puppeteer/issues/1313)<!-- -->.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Keyboard` class.
+
+## Example 1
+
+An example of holding down `Shift` in order to select and delete some text:
+
+```js
+await page.keyboard.type('Hello World!');
+await page.keyboard.press('ArrowLeft');
 
-## Properties
+await page.keyboard.down('Shift');
+for (let i = 0; i < ' World'.length; i++)
+  await page.keyboard.press('ArrowLeft');
+await page.keyboard.up('Shift');
 
-|  Property | Modifiers | Type | Description |
-|  --- | --- | --- | --- |
-|  [\_client](./puppeteer.keyboard._client.md) |  | [CDPSession](./puppeteer.cdpsession.md) |  |
-|  [\_modifiers](./puppeteer.keyboard._modifiers.md) |  | number |  |
-|  [\_pressedKeys](./puppeteer.keyboard._pressedkeys.md) |  | Set&lt;string&gt; |  |
+await page.keyboard.press('Backspace');
+// Result text will end up saying 'Hello!'
+
+```
+
+## Example 2
+
+An example of pressing `A`
+
+```js
+await page.keyboard.down('Shift');
+await page.keyboard.press('KeyA');
+await page.keyboard.up('Shift');
+
+```
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [down(key, options)](./puppeteer.keyboard.down.md) |  |  |
-|  [press(key, options)](./puppeteer.keyboard.press.md) |  |  |
-|  [sendCharacter(char)](./puppeteer.keyboard.sendcharacter.md) |  |  |
-|  [type(text, options)](./puppeteer.keyboard.type.md) |  |  |
-|  [up(key)](./puppeteer.keyboard.up.md) |  |  |
+|  [down(key, options)](./puppeteer.keyboard.down.md) |  | Dispatches a <code>keydown</code> event. |
+|  [press(key, options)](./puppeteer.keyboard.press.md) |  | Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->. |
+|  [sendCharacter(char)](./puppeteer.keyboard.sendcharacter.md) |  | Dispatches a <code>keypress</code> and <code>input</code> event. This does not send a <code>keydown</code> or <code>keyup</code> event. |
+|  [type(text, options)](./puppeteer.keyboard.type.md) |  | Sends a <code>keydown</code>, <code>keypress</code>/<code>input</code>, and <code>keyup</code> event for each character in the text. |
+|  [up(key)](./puppeteer.keyboard.up.md) |  | Dispatches a <code>keyup</code> event. |
 

new-docs/puppeteer.keyboard.press.md

@@ -4,6 +4,8 @@
 
 ## Keyboard.press() method
 
+Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -17,10 +19,16 @@ press(key: KeyInput, options?: {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  key | [KeyInput](./puppeteer.keyinput.md) |  |
-|  options | { delay?: number; text?: string; } |  |
+|  key | [KeyInput](./puppeteer.keyinput.md) | Name of key to press, such as <code>ArrowLeft</code>. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. |
+|  options | { delay?: number; text?: string; } | An object of options. Accepts text which, if specified, generates an input event with this text. Accepts delay which, if specified, is the time to wait between <code>keydown</code> and <code>keyup</code> in milliseconds. Defaults to 0. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`<!-- -->/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
+
+Modifier keys DO effect [Keyboard.press()](./puppeteer.keyboard.press.md)<!-- -->. Holding down `Shift` will type the text in upper case.
+

new-docs/puppeteer.keyboard.sendcharacter.md

@@ -4,6 +4,8 @@
 
 ## Keyboard.sendCharacter() method
 
+Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,21 @@ sendCharacter(char: string): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  char | string |  |
+|  char | string | Character to send into the page. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+Modifier keys DO NOT effect [Keyboard.sendCharacter](./puppeteer.keyboard.sendcharacter.md)<!-- -->. Holding down `Shift` will not type the text in upper case.
+
+## Example
+
+
+```js
+page.keyboard.sendCharacter('嗨');
+
+```
+

new-docs/puppeteer.keyboard.type.md

@@ -4,6 +4,8 @@
 
 ## Keyboard.type() method
 
+Sends a `keydown`<!-- -->, `keypress`<!-- -->/`input`<!-- -->, and `keyup` event for each character in the text.
+
 <b>Signature:</b>
 
 ```typescript
@@ -16,10 +18,25 @@ type(text: string, options?: {
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  text | string |  |
-|  options | { delay?: number; } |  |
+|  text | string | A text to type into a focused element. |
+|  options | { delay?: number; } | An object of options. Accepts delay which, if specified, is the time to wait between <code>keydown</code> and <code>keyup</code> in milliseconds. Defaults to 0. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+To press a special key, like `Control` or `ArrowDown`<!-- -->, use [Keyboard.press()](./puppeteer.keyboard.press.md)<!-- -->.
+
+Modifier keys DO NOT effect `keyboard.type`<!-- -->. Holding down `Shift` will not type the text in upper case.
+
+## Example
+
+
+```js
+await page.keyboard.type('Hello'); // Types instantly
+await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
+
+```
+

new-docs/puppeteer.keyboard.up.md

@@ -4,6 +4,8 @@
 
 ## Keyboard.up() method
 
+Dispatches a `keyup` event.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,7 +16,7 @@ up(key: KeyInput): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  key | [KeyInput](./puppeteer.keyinput.md) |  |
+|  key | [KeyInput](./puppeteer.keyinput.md) | Name of key to release, such as <code>ArrowLeft</code>. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. |
 
 <b>Returns:</b>
 

new-docs/puppeteer.md

@@ -26,7 +26,7 @@
 |  [HTTPRequest](./puppeteer.httprequest.md) |  |
 |  [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. |
 |  [JSHandle](./puppeteer.jshandle.md) |  |
-|  [Keyboard](./puppeteer.keyboard.md) |  |
+|  [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md)<!-- -->, which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. |
 |  [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 Puppeteer module provides a method to launch a browser instance. |