Improve documentation

[macklinu]

Description

This is an umbrella issue for improving the documentation of eslint-plugin-promise. I would like to take the following steps:

• Move rule documentation to docs/rules/{{ruleName}}.md. This seems to be a standard practice with most ESLint plugins I've seen (e.g. eslint-plugin-jest and eslint-plugin-react), as well as ESLint itself. If more documentation gets added for each rule (valid/invalid cases, links to further reading) and all rule documentation was in the README, the document would become pretty large and hard to navigate as opposed to having separate rule documents. As part of this, we would also need to open a PR to change the documentation link in eslint-rule-documentation. Fix eslint-plugin-promise docs location jfmengels/eslint-rule-documentation#32
• Standardize the rule document format. I'd like to use the format I see in ESLint rules (like prefer-const), which include the following headings
  • h1. Rule description (rule-name)
    • mention if rule is fixable
    • provide a brief rule description
  • h2. Rule Details
    • include invalid and valid code examples for the default rule configuration
  • h2. Options
    • show an example of how to configure the eslint-plugin-promise rule with options (like a snippet from an .eslintrc file)
    • explain each option, including invalid and valid use cases for each option configuration
  • h2. When Not To Use It
    • briefly explain when not to use the rule
  • h2. Further Reading (optional)
    • provide links to articles or documentation that may provide a deeper understanding of the why of the rule
  • h2. Related Rules (optional)
    • provide links to related eslint-plugin-promise rules

I will take care of the first step this week and slowly open PRs over time to improve the documentation of each rule. Contributions are also welcome! 😄