Documentation Improvements

docs/rules/always-return.md

@@ -1,22 +1,19 @@
 # Return inside each `then()` to create readable and reusable Promise chains (always-return)
 
 Ensure that inside a `then()` you make sure to `return` a new promise or value.
-See http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html (rule #5)
-for more info on why that's a good idea.
 
-We also allow someone to `throw` inside a `then()` which is essentially the same
-as `return Promise.reject()`.
+## Rule Details
 
-#### Valid
+Using a promise inside a `then()` without returning it (or using `await`) means
+that a potential error from that promise will not be caught in subsequent
+`catch()` callbacks. Additionally, returning a non-promise wraps it into a
+Promise, allowing it to be used in promise chains, which is convenient when
+mixing synchronous and asynchronous code.
 
-```js
-myPromise.then((val) => val * 2));
-myPromise.then(function(val) { return val * 2; });
-myPromise.then(doSomething); // could be either
-myPromise.then((b) => { if (b) { return "yes" } else { return "no" } });
-```
+We also allow someone to `throw` inside a `then()` which is essentially the same
+as `return Promise.reject()` in this scenario.
 
-#### Invalid
+Examples of **incorrect** code for this rule:
 
 ```js
 myPromise.then(function(val) {})
@@ -31,3 +28,29 @@ myPromise.then(b => {
   }
 })
 ```
+
+Examples of **correct** code for this rule:
+
+```js
+myPromise.then((val) => val * 2);
+myPromise.then(function(val) { return val * 2; });
+myPromise.then(doSomething); // could be either
+myPromise.then((b) => { if (b) { return 'yes' } else { return 'no' } });
+```
+
+## When Not To Use It
+
+If you want to allow non-returning `then()` callbacks, for example for
+synchronous side-effects like below, you can safely disable this rule.
+
+```js
+myPromise.then(val => {
+  console.log('promise complete')
+  console.log(val)
+})
+```
+
+## Further Reading
+
+- [We have a problem with promises](http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html)
+  (Rookie mistake #5: using side effects instead of returning)

docs/rules/avoid-new.md

@@ -1,3 +1,45 @@
 # Avoid creating `new` promises outside of utility libs (use [pify][] instead) (avoid-new)
 
+Avoid using `new Promise` in favour of utility libraries or
+`Promise.resolve`/`reject`.
+
+## Rule Details
+
+Creating promises using `new Promise` can be used to promisify Node-style
+callbacks. However, you can use libraries such as [pify][] or Node's
+[`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original)
+instead.
+
+`new Promise` is also sometimes misused to wrap a value or
+error into a promise. However, this can be done more concisely and clearly with
+`Promise.resolve` and `Promise.reject`.
+
+Examples of **incorrect** code for this rule:
+
+```js
+function promisifiedFn(arg) {
+  return new Promise((resolve, reject) => {
+    callbackStyleFn(arg, (error, result) => error ? reject(error) : resolve(result))
+  })
+}
+
+new Promise((resolve, reject) => resolve(1))
+new Promise((resolve, reject) => reject(new Error('oops')))
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const pify = require('pify')
+const promisifiedFn = pify(callbackStyleFn)
+
+Promise.resolve(1)
+Promise.reject(new Error('oops'))
+```
+
+## When Not To Use It
+
+If you are creating a utility library like pify or do not want to be notified
+when using `new Promise`, you can safely disable this rule.
+
 [pify]: https://www.npmjs.com/package/pify

docs/rules/catch-or-return.md

@@ -3,69 +3,119 @@
 Ensure that each time a `then()` is applied to a promise, a `catch()` is applied
 as well. Exceptions are made if you are returning that promise.
 
-#### Valid
+## Rule Details
+
+If a promise is not handled correctly, any error from that promise can cause
+unhandled promise rejections. A promise can be handled using `catch()` or
+returning it from a function, which will mean that it's the caller's
+responsibility to handle the promise.
+
+Examples of **incorrect** code for this rule:
 
 ```js
-myPromise.then(doSomething).catch(errors)
+myPromise.then(doSomething)
+myPromise.then(doSomething, handleErrors) // catch() may be a little better
+```
+
+Examples of **correct** code for this rule:
+
+```js
+myPromise.then(doSomething).catch(handleErrors)
 myPromise
   .then(doSomething)
   .then(doSomethingElse)
-  .catch(errors)
+  .catch(handleErrors)
 function doSomethingElse() {
   return myPromise.then(doSomething)
 }
 ```
 
-#### Invalid
+## Options
+
+### `allowThen`
+
+The second argument to `then()` can also be used to handle a promise rejection,
+but it won't catch any errors from the first argument callback. Because of this,
+this rule reports usage of `then()` with two arguments without `catch()` by
+default.
+
+However, you can use `{ allowThen: true }` to allow using `then()` with two
+arguments instead of `catch()` to handle promise rejections.
+
+Examples of **incorrect** code for the default `{ allowThen: false }` option:
 
 ```js
-myPromise.then(doSomething)
-myPromise.then(doSomething, catchErrors) // catch() may be a little better
-function doSomethingElse() {
-  return myPromise.then(doSomething)
-}
+myPromise.then(doSomething, handleErrors)
+```
+
+Examples of **correct** code for the `{ allowThen: true }` option:
+
+```js
+myPromise.then(doSomething, handleErrors)
+myPromise.then(doSomething).catch(handleErrors)
+```
+
+### `allowFinally`
+
+This option allows `.finally()` to be used after `catch()` at the end of the
+promise chain. This is different from adding `'finally'` as a
+`terminationMethod` because it will still require the Promise chain to be
+"caught" beforehand.
+
+Examples of **incorrect** code for the default `{ allowFinally: false }` option:
+
+```js
+myPromise
+  .then(doSomething)
+  .catch(handleErrors)
+  .finally(cleanUp)
 ```
 
-#### Options
+Examples of **correct** code for the `{ allowFinally: true }` option:
 
-##### `allowThen`
+```js
+myPromise
+  .then(doSomething)
+  .catch(handleErrors)
+  .finally(cleanUp)
+```
 
-You can pass an `{ allowThen: true }` as an option to this rule to allow for
-`.then(null, fn)` to be used instead of `catch()` at the end of the promise
-chain.
+### `terminationMethod`
 
-##### `allowFinally`
+This option allows for specifying different method names to allow instead of
+`catch()` at the end of the promise chain. This is
+useful for many non-standard Promise implementations. You can use a single
+string or an array of strings.
 
-You can pass an `{ allowFinally: true }` as an option to this rule to allow for
-`.finally(fn)` to be used after `catch()` at the end of the promise chain. This
-is different from adding `'finally'` as a `terminationMethod` because it will
-still require the Promise chain to be "caught" beforehand.
+Examples of **incorrect** code for the `{ terminationMethod: 'done' }` option:
 
-##### `terminationMethod`
+```js
+myPromise.then(doSomething).catch(handleErrors)
+```
 
-You can pass a `{ terminationMethod: 'done' }` as an option to this rule to
-require `done()` instead of `catch()` at the end of the promise chain. This is
-useful for many non-standard Promise implementations.
+Examples of **correct** code for the `{ terminationMethod: 'done' }` option:
 
-You can also pass an array of methods such as
-`{ terminationMethod: ['catch', 'asCallback', 'finally'] }`.
+```js
+myPromise.then(doSomething).done(handleErrors)
+```
 
-This will allow any of
+Examples of **correct** code for the
+`{ terminationMethod: ['catch', 'asCallback', 'finally'] }` option:
 
 ```js
-Promise.resolve(1)
-  .then(() => {
-    throw new Error('oops')
-  })
-  .catch(logerror)
-Promise.resolve(1)
-  .then(() => {
-    throw new Error('oops')
-  })
-  .asCallback(cb)
-Promise.resolve(1)
-  .then(() => {
-    throw new Error('oops')
-  })
-  .finally(cleanUp)
+myPromise.then(doSomething).catch(handleErrors)
+myPromise.then(doSomething).asCallback(handleErrors)
+myPromise.then(doSomething).finally(handleErrors)
 ```
+
+## When Not To Use It
+
+If you do not want to be notified about not handling promises by `catch`ing or
+`return`ing, such as if you have a custom `unhandledRejection`
+(`unhandledrejection` in the browser) handler, you can safely disable this rule.
+
+## Further Reading
+
+- [We have a problem with promises](http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html)
+  (Advanced mistake #2: `then(resolveHandler).catch(rejectHandler)` isn't
+  exactly the same as `then(resolveHandler, rejectHandler)`)

docs/rules/no-native.md

@@ -4,15 +4,26 @@ Ensure that `Promise` is included fresh in each file instead of relying on the
 existence of a native promise implementation. Helpful if you want to use
 `bluebird` or if you don't intend to use an ES6 Promise shim.
 
-#### Valid
+## Rule Details
+
+If you are targeting an ES5 environment where native promises aren't supported,
+ensuring that `Promise` is included from a promise library prevents bugs from
+`Promise` being undefined.
+
+Examples of **incorrect** code for this rule:
 
 ```js
-var Promise = require('bluebird')
-var x = Promise.resolve('good')
+var x = Promise.resolve('bad')
 ```
 
-#### Invalid
+Examples of **correct** code for this rule:
 
 ```js
-var x = Promise.resolve('bad')
+var Promise = require('bluebird')
+var x = Promise.resolve('good')
 ```
+
+## When Not To Use It
+
+If you are targeting an environment that supports native promises, or using a
+Promise shim, you should disable this rule.

docs/rules/no-nesting.md

@@ -1,15 +1,15 @@
 # Avoid nested `then()` or `catch()` statements (no-nesting)
 
-#### Valid
+Nesting `then()` or `catch()` statements making code harder to understand and
+maintain. Instead, you should return a promise from `then()` or `catch()` to
+chain the promises.
 
-```js
-myPromise
-  .then(doSomething)
-  .then(doSomethingElse)
-  .catch(errors)
-```
+## Rule Details
+
+Nesting `then()` or `catch()` statements is frequently redundant and does not
+utilise promise chaining. This can result in code similar to "callback hell".
 
-#### Invalid
+Examples of **incorrect** code for this rule:
 
 ```js
 myPromise.then(val =>
@@ -28,3 +28,24 @@ myPromise.catch(err =>
   doSomething(err).catch(errors)
 )
 ```
+
+Examples of **correct** code for this rule:
+
+```js
+myPromise
+  .then(doSomething)
+  .then(doSomethingElse)
+  .catch(errors)
+```
+
+## When Not To Use It
+
+If you want to nest promises, for example to have different `catch()` handlers
+to handle the different promises, you can safely disable this rule.
+
+## Further Reading
+
+- [Promises chaining on Javascript.info](https://javascript.info/promise-chaining)
+- [Using Promises on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#Common_mistakes)
+- [We have a problem with promises](https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html)
+  (Rookie mistake #1: the promisey pyramid of doom)

docs/rules/no-new-statics.md

@@ -11,7 +11,7 @@ problems reported by this rule.
 This rule is aimed at flagging instances where a Promise static method is called
 with `new`.
 
-Examples for **incorrect** code for this rule:
+Examples of **incorrect** code for this rule:
 
 ```js
 new Promise.resolve(value)
@@ -20,7 +20,7 @@ new Promise.race([p1, p2])
 new Promise.all([p1, p2])
 ```
 
-Examples for **correct** code for this rule:
+Examples of **correct** code for this rule:
 
 ```js
 Promise.resolve(value)
@@ -31,5 +31,6 @@ Promise.all([p1, p2])
 
 ## When Not To Use It
 
-If you do not want to be notified when calling `new` on a Promise static method,
-you can safely disable this rule.
+If you do not want to be notified when calling `new` on a Promise static method
+(for example when using a type checker like Flow or Typescript), you can safely
+disable this rule.