docs: supply missing docs (#503)

**What is the purpose of this pull request?**

- [x] Documentation update

**What changes did you make? (Give an overview)**

Supply missing doc pages. Draws heavily again from #199.

Also:
- uses latest Node URLs

Fixes #214.

README.md

@@ -132,8 +132,7 @@ or start with the recommended rule set:
 
 [util.callbackify]:
   https://nodejs.org/docs/latest/api/util.html#utilcallbackifyoriginal
-[util.promisify]:
-  https://nodejs.org/dist/latest-v8.x/docs/api/util.html#util_util_promisify_original
+[util.promisify]: https://nodejs.org/api/util.html#util_util_promisify_original
 [@aaditmshah]: https://github.com/aaditmshah
 [@macklinu]: https://github.com/macklinu
 [@xjamundx]: https://github.com/xjamundx

docs/rules/avoid-new.md

@@ -5,5 +5,46 @@
 
 <!-- end auto-generated rule header -->
 
-[util.promisify]:
-  https://nodejs.org/dist/latest-v8.x/docs/api/util.html#util_util_promisify_original
+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 Node's [`util.promisify`]() 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
+import util from 'util'
+const promisifiedFn = util.promisify(callbackStyleFn)
+
+Promise.resolve(1)
+Promise.reject(new Error('oops'))
+```
+
+## When Not To Use It
+
+If you are creating a utility library without [util.promisify]() or do not want
+to be notified when using `new Promise`, you can safely disable this rule.
+
+[util.promisify]: https://nodejs.org/api/util.html#util_util_promisify_original

docs/rules/no-callback-in-promise.md

@@ -68,9 +68,9 @@ callback code instead of combining the approaches.
 [promise.prototype.catch()]:
   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch
 [setimmediate()]:
-  https://nodejs.org/docs/latest-v14.x/api/timers.html#timers_setimmediate_callback_args
+  https://nodejs.org/docs/latest/api/timers.html#timers_setimmediate_callback_args
 [process.nexttick()]:
-  https://nodejs.org/docs/latest-v14.x/api/process.html#process_process_nexttick_callback_args
+  https://nodejs.org/docs/latest/api/process.html#process_process_nexttick_callback_args
 [settimeout()]:
   https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout
 

docs/rules/no-promise-in-callback.md

@@ -4,3 +4,33 @@
 `recommended`.
 
 <!-- end auto-generated rule header -->
+
+Discourages the use of promises inside callbacks.
+
+## Rule Details
+
+Promises and callbacks are different ways to handle asynchronous code and should
+not be mixed.
+
+Examples of **incorrect** code for this rule:
+
+```js
+doSomething((err, val) => {
+  if (err) console.error(err)
+  else doSomethingElse(val).then(console.log)
+})
+```
+
+Examples of **correct** code for this rule:
+
+```js
+promisify(doSomething)()
+  .then(doSomethingElse)
+  .then(console.log)
+  .catch(console.error)
+```
+
+## When Not To Use It
+
+If you do not want to be notified when using promises inside of callbacks, you
+can safely disable this rule.