docs: add more keyboard examples for typing (#1176)

This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods.

fixes #723

docs/api.md

@@ -1162,18 +1162,25 @@ For finer control, you can use [`keyboard.down`](#keyboarddownkey-options), [`ke
 
 An example of holding down `Shift` in order to select and delete some text:
 ```js
-page.keyboard.type('Hello World!');
+await page.keyboard.type('Hello World!');
-page.keyboard.press('ArrowLeft');
+await page.keyboard.press('ArrowLeft');
 
-page.keyboard.down('Shift');
+await page.keyboard.down('Shift');
 for (let i = 0; i < ' World'.length; i++)
-  page.keyboard.press('ArrowLeft');
+  await page.keyboard.press('ArrowLeft');
-page.keyboard.up('Shift');
+await page.keyboard.up('Shift');
 
-page.keyboard.press('Backspace');
+await page.keyboard.press('Backspace');
 // Result text will end up saying 'Hello!'
 ```
 
+An example of pressing `A`
+```js
+await page.keyboard.down('Shift');
+await page.keyboard.press('KeyA');
+await page.keyboard.up('Shift');
+```
+
 #### keyboard.down(key[, options])
 - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
 - `options` <[Object]>
@@ -1188,6 +1195,8 @@ If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key
 
 After the key is pressed once, subsequent calls to [`keyboard.down`](#keyboarddownkey-options) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [`keyboard.up`](#keyboardupkey).
 
+> **NOTE** Modifier keys DO effect `keyboard.down`. Holding down `Shift` will type the text in upper case.
+
 #### keyboard.press(key[, options])
 - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
 - `options` <[Object]>
@@ -1195,6 +1204,10 @@ After the key is pressed once, subsequent calls to [`keyboard.down`](#keyboarddo
   - `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
 - returns: <[Promise]>
 
+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.
+
+> **NOTE** Modifier keys DO effect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
+
 Shortcut for [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
 
 #### keyboard.sendCharacter(char)
@@ -1207,6 +1220,8 @@ Dispatches a `keypress` and `input` event. This does not send a `keydown` or `ke
 page.keyboard.sendCharacter('嗨');
 ```
 
+> **NOTE** Modifier keys DO NOT effect `keyboard.sendCharacter`. Holding down `Shift` will not type the text in upper case.
+
 #### keyboard.type(text, options)
 - `text` <[string]> A text to type into a focused element.
 - `options` <[Object]>
@@ -1222,6 +1237,8 @@ page.keyboard.type('Hello'); // Types instantly
 page.keyboard.type('World', {delay: 100}); // Types slower, like a user
 ```
 
+> **NOTE** Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
+
 #### keyboard.up(key)
 - `key` <[string]> Name of key to release, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
 - returns: <[Promise]>
@@ -1814,6 +1831,10 @@ Returns a JSON representation of the object. The JSON is generated by running [`
 
 Focuses the element, and then uses [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
 
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
+
+> **NOTE** Modifier keys DO effect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
+
 #### elementHandle.screenshot([options])
 - `options` <[Object]> Same options as in [page.screenshot](#pagescreenshotoptions).
 - returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot.
@@ -1845,6 +1866,13 @@ elementHandle.type('Hello'); // Types instantly
 elementHandle.type('World', {delay: 100}); // Types slower, like a user
 ```
 
+An example of typing into a text field and then submitting the form:
+```js
+const elementHandle = await page.$('input');
+await elementHandle.type('some text');
+await elementHandle.press('Enter');
+```
+
 #### elementHandle.uploadFile(...filePaths)
 - `...filePaths` <...[string]> Sets the value of the file input these paths. If some of the  `filePaths` are relative paths, then they are resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
 - returns: <[Promise]>