docs: add for prefer-await-to-callbacks; fixes #118 (#491)

README.md

@@ -112,7 +112,7 @@ or start with the recommended rule set:
 | [no-return-in-finally](docs/rules/no-return-in-finally.md)           | Disallow return statements in `finally()`.                                             |     | ✅  |     |     |
 | [no-return-wrap](docs/rules/no-return-wrap.md)                       | Disallow wrapping values in `Promise.resolve` or `Promise.reject` when not needed.     | ✅  |     |     |     |
 | [param-names](docs/rules/param-names.md)                             | Enforce consistent param names and ordering when creating new promises.                | ✅  |     |     |     |
-| [prefer-await-to-callbacks](docs/rules/prefer-await-to-callbacks.md) | Prefer async/await to the callback pattern.                                            |     |     |     |     |
+| [prefer-await-to-callbacks](docs/rules/prefer-await-to-callbacks.md) | Prefer `async`/`await` to the callback pattern.                                        |     |     |     |     |
 | [prefer-await-to-then](docs/rules/prefer-await-to-then.md)           | Prefer `await` to `then()`/`catch()`/`finally()` for reading Promise values.           |     |     |     |     |
 | [valid-params](docs/rules/valid-params.md)                           | Enforces the proper number of arguments are passed to Promise functions.               |     | ✅  |     |     |
 

docs/rules/prefer-await-to-callbacks.md

@@ -1,3 +1,37 @@
-# Prefer async/await to the callback pattern (`promise/prefer-await-to-callbacks`)
+# Prefer `async`/`await` to the callback pattern (`promise/prefer-await-to-callbacks`)
 
 <!-- end auto-generated rule header -->
+
+`async`/`await` is a clearer pattern to follow than using callbacks.
+
+## Rule details
+
+ES2017's `async`/`await` makes it easier to deal with asynchronous code than the
+callback pattern.
+
+Examples of **incorrect** code for this rule:
+
+```js
+cb()
+callback()
+doSomething(arg, (err) => {})
+function doSomethingElse(cb) {}
+```
+
+Examples of **correct** code for this rule:
+
+```js
+await doSomething(arg)
+async function doSomethingElse() {}
+yield yieldValue(err => {})
+eventEmitter.on('error', err => {})
+```
+
+## When Not To Use It
+
+If you are not targeting an ES2017 or higher environment and cannot transpile
+`async`/`await`, you should disable this rule.
+
+## Further Reading
+
+- [Making asynchronous programming easier with async and await on MDN](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises)

rules/prefer-await-to-callbacks.js

@@ -7,7 +7,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'Prefer async/await to the callback pattern.',
+      description: 'Prefer `async`/`await` to the callback pattern.',
       url: getDocsUrl('prefer-await-to-callbacks'),
     },
     messages: {