Docs: Update rule descriptions for consistency (#159)

* Clarity
* Punctuation
* Grammar
* Backticks
* Formatting

Author: bmish

README.md

@@ -47,27 +47,27 @@ Then configure the rules you want to use under the rules section.
 <!-- __BEGIN AUTOGENERATED TABLE__ -->
 Name | ✔️ | 🛠 | 💡 | Description
 ----- | ----- | ----- | ----- | -----
-[consistent-output](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/consistent-output.md) |  |  |  | enforce consistent use of output assertions in rule tests
-[fixer-return](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/fixer-return.md) | ✔️ |  |  | require fixer function to return a fix
+[consistent-output](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/consistent-output.md) |  |  |  | enforce consistent use of `output` assertions in rule tests
+[fixer-return](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/fixer-return.md) | ✔️ |  |  | require fixer functions to return a fix
 [meta-property-ordering](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/meta-property-ordering.md) |  | 🛠 |  | enforce the order of meta properties
 [no-deprecated-context-methods](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-deprecated-context-methods.md) |  | 🛠 |  | disallow usage of deprecated methods on rule context objects
-[no-deprecated-report-api](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-deprecated-report-api.md) | ✔️ | 🛠 |  | disallow use of the deprecated context.report() API
+[no-deprecated-report-api](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-deprecated-report-api.md) | ✔️ | 🛠 |  | disallow the version of `context.report()` with multiple arguments
 [no-identical-tests](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-identical-tests.md) | ✔️ | 🛠 |  | disallow identical tests
 [no-missing-placeholders](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-missing-placeholders.md) | ✔️ |  |  | disallow missing placeholders in rule report messages
 [no-only-tests](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-only-tests.md) |  |  | 💡 | disallow the test case property `only`
 [no-unused-placeholders](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-unused-placeholders.md) | ✔️ |  |  | disallow unused placeholders in rule report messages
-[no-useless-token-range](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-useless-token-range.md) | ✔️ | 🛠 |  | disallow unnecessary calls to sourceCode.getFirstToken and sourceCode.getLastToken
-[prefer-object-rule](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-object-rule.md) |  | 🛠 |  | disallow rule exports where the export is a function.
-[prefer-output-null](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-output-null.md) |  | 🛠 |  | disallow invalid RuleTester test cases with the output the same as the code.
-[prefer-placeholders](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-placeholders.md) |  |  |  | disallow template literals as report messages
-[prefer-replace-text](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-replace-text.md) |  |  |  | require using replaceText instead of replaceTextRange.
+[no-useless-token-range](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-useless-token-range.md) | ✔️ | 🛠 |  | disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()`
+[prefer-object-rule](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-object-rule.md) |  | 🛠 |  | disallow rule exports where the export is a function
+[prefer-output-null](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-output-null.md) |  | 🛠 |  | disallow invalid RuleTester test cases where the `output` matches the `code`
+[prefer-placeholders](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-placeholders.md) |  |  |  | require using placeholders for dynamic report messages
+[prefer-replace-text](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-replace-text.md) |  |  |  | require using `replaceText()` instead of `replaceTextRange()`
 [report-message-format](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/report-message-format.md) |  |  |  | enforce a consistent format for rule report messages
-[require-meta-docs-description](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-docs-description.md) |  |  |  | require rules to implement a meta.docs.description property with the correct format
-[require-meta-docs-url](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-docs-url.md) |  | 🛠 |  | require rules to implement a meta.docs.url property
-[require-meta-fixable](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-fixable.md) | ✔️ |  |  | require rules to implement a meta.fixable property
+[require-meta-docs-description](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-docs-description.md) |  |  |  | require rules to implement a `meta.docs.description` property with the correct format
+[require-meta-docs-url](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-docs-url.md) |  | 🛠 |  | require rules to implement a `meta.docs.url` property
+[require-meta-fixable](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-fixable.md) | ✔️ |  |  | require rules to implement a `meta.fixable` property
 [require-meta-has-suggestions](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-has-suggestions.md) |  |  |  | require suggestable rules to implement a `meta.hasSuggestions` property
-[require-meta-schema](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-schema.md) |  | 🛠 |  | require rules to implement a meta.schema property
-[require-meta-type](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-type.md) |  |  |  | require rules to implement a meta.type property
+[require-meta-schema](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-schema.md) |  | 🛠 |  | require rules to implement a `meta.schema` property
+[require-meta-type](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-type.md) |  |  |  | require rules to implement a `meta.type` property
 [test-case-property-ordering](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/test-case-property-ordering.md) |  | 🛠 |  | require the properties of a test case to be placed in a consistent order
 [test-case-shorthand-strings](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/test-case-shorthand-strings.md) |  | 🛠 |  | enforce consistent usage of shorthand strings for test cases with no options
 <!-- __END AUTOGENERATED TABLE__ -->

docs/rules/consistent-output.md

@@ -1,4 +1,4 @@
-# Enforce consistent use of output assertions in rule tests (consistent-output)
+# Enforce consistent use of `output` assertions in rule tests (consistent-output)
 
 When writing tests for a fixable rule with `RuleTester`, you can assert the autofix output of your test cases. However, it can be easy to forget to assert the output of a particular test case.
 

docs/rules/fixer-return.md

@@ -1,4 +1,4 @@
-# Require fixer function to return a fix (fixer-return)
+# Require fixer functions to return a fix (fixer-return)
 
 ✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.
 

docs/rules/no-deprecated-report-api.md

@@ -1,10 +1,15 @@
-# Disallow use of the deprecated context.report() API (no-deprecated-report-api)
+# Disallow the version of `context.report()` with multiple arguments (no-deprecated-report-api)
 
 ✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.
 
 ⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#-fix) can automatically fix some of the problems reported by this rule.
 
-ESLint has two APIs that rules can use to report problems. The [deprecated API](http://eslint.org/docs/developer-guide/working-with-rules-deprecated) accepts multiple arguments: `context.report(node, [loc], message)`. The ["new API"](http://eslint.org/docs/developer-guide/working-with-rules#contextreport) accepts a single argument: an object containing information about the reported problem. It is recommended that all rules use the new API.
+ESLint has two APIs that rules can use to report problems.
+
+* The [deprecated API](http://eslint.org/docs/developer-guide/working-with-rules-deprecated) accepts multiple arguments: `context.report(node, [loc], message)`.
+* The ["new API"](http://eslint.org/docs/developer-guide/working-with-rules#contextreport) accepts a single argument: an object containing information about the reported problem.
+
+It is recommended that all rules use the new API.
 
 ## Rule Details
 

docs/rules/no-unused-placeholders.md

@@ -6,7 +6,7 @@ This rule aims to disallow unused placeholders in rule report messages.
 
 ## Rule Details
 
-Reports when a context.report call contains a data property that does not have a corresponding placeholder in the report message.
+Reports when a `context.report()` call contains a data property that does not have a corresponding placeholder in the report message.
 
 Examples of **incorrect** code for this rule:
 

docs/rules/no-useless-token-range.md

@@ -1,4 +1,4 @@
-# Disallow unnecessary calls to sourceCode.getFirstToken and sourceCode.getLastToken (no-useless-token-range)
+# Disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()` (no-useless-token-range)
 
 ✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.
 
@@ -8,7 +8,7 @@ AST nodes always start and end with tokens. As a result, the start index of the
 
 ## Rule Details
 
-This rule aims to avoid unnecessary calls to `sourceCode.getFirstToken` and `sourceCode.getLastToken`.
+This rule aims to avoid unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()`.
 
 Examples of **incorrect** code for this rule:
 

docs/rules/prefer-object-rule.md

@@ -1,4 +1,4 @@
-# Disallow rule exports where the export is a function. (prefer-object-rule)
+# Disallow rule exports where the export is a function (prefer-object-rule)
 
 ⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#-fix) can automatically fix some of the problems reported by this rule.
 

docs/rules/prefer-output-null.md

@@ -1,4 +1,4 @@
-# Disallow invalid RuleTester test cases with the output the same as the code. (prefer-output-null)
+# Disallow invalid RuleTester test cases where the `output` matches the `code` (prefer-output-null)
 
 ⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#-fix) can automatically fix some of the problems reported by this rule.
 

docs/rules/prefer-placeholders.md

@@ -1,4 +1,4 @@
-# Disallow template literals as report messages (prefer-placeholders)
+# Require using placeholders for dynamic report messages (prefer-placeholders)
 
 Report messages in rules can have placeholders surrounded by curly brackets.
 

docs/rules/prefer-replace-text.md

@@ -1,8 +1,8 @@
-# Require using replaceText instead of replaceTextRange. (prefer-replace-text)
+# Require using `replaceText()` instead of `replaceTextRange()` (prefer-replace-text)
 
 ## Rule Details
 
-The rule reports an error if `replaceTextRange`'s first argument is an array of identical array elements. It can be easily replaced by `replaceText` to improve readability.
+The rule reports an error if `replaceTextRange()`'s first argument is an array of identical array elements. It can be easily replaced by `replaceText()` to improve readability.
 
 Examples of **incorrect** code for this rule:
 

docs/rules/require-meta-docs-description.md

@@ -1,4 +1,4 @@
-# Require rules to implement a meta.docs.description property with the correct format (require-meta-docs-description)
+# Require rules to implement a `meta.docs.description` property with the correct format (require-meta-docs-description)
 
 Defining a clear and consistent description for each rule helps developers understand what they're used for.
 

docs/rules/require-meta-docs-url.md

@@ -1,4 +1,4 @@
-# Require rules to implement a meta.docs.url property (require-meta-docs-url)
+# Require rules to implement a `meta.docs.url` property (require-meta-docs-url)
 
 ⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#-fix) can automatically fix some of the problems reported by this rule.
 

docs/rules/require-meta-fixable.md

@@ -1,4 +1,4 @@
-# Require rules to implement a meta.fixable property (require-meta-fixable)
+# Require rules to implement a `meta.fixable` property (require-meta-fixable)
 
 ✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.
 

docs/rules/require-meta-schema.md

@@ -1,4 +1,4 @@
-# Require rules to implement a meta.schema property (require-meta-schema)
+# Require rules to implement a `meta.schema` property (require-meta-schema)
 
 ⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#-fix) can automatically fix some of the problems reported by this rule.
 

docs/rules/require-meta-type.md

@@ -1,8 +1,8 @@
-# Require rules to implement a meta.type property (require-meta-type)
+# Require rules to implement a `meta.type` property (require-meta-type)
 
 ESLint v5.9.0 introduces a new `--fix-type` option for the command line interface. This option allows users to filter the type of fixes applied when using `--fix`.
 
-Fixes in custom rules will not be applied when using `--fix-type` unless they include a meta.type field.
+Fixes in custom rules will not be applied when using `--fix-type` unless they include a `meta.type` field.
 
 ## Rule Details
 

lib/rules/consistent-output.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Enforce consistent use of output assertions in rule tests
+ * @fileoverview Enforce consistent use of `output` assertions in rule tests
  * @author Teddy Katz
  */
 
@@ -15,7 +15,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'enforce consistent use of output assertions in rule tests',
+      description: 'enforce consistent use of `output` assertions in rule tests',
       category: 'Tests',
       recommended: false,
     },

lib/rules/fixer-return.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Require fixer function to return a fix
+ * @fileoverview require fixer functions to return a fix
  * @author 薛定谔的猫<[email protected]>
  */
 
@@ -20,7 +20,7 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'require fixer function to return a fix',
+      description: 'require fixer functions to return a fix',
       category: 'Possible Errors',
       recommended: true,
     },

lib/rules/no-deprecated-report-api.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview disallow use of the deprecated context.report() API
+ * @fileoverview Disallow the version of `context.report()` with multiple arguments
  * @author Teddy Katz
  */
 
@@ -15,7 +15,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'disallow use of the deprecated context.report() API',
+      description: 'disallow the version of `context.report()` with multiple arguments',
       category: 'Rules',
       recommended: true,
     },

lib/rules/no-useless-token-range.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Disallow unnecessary calls to sourceCode.getFirstToken and sourceCode.getLastToken
+ * @fileoverview Disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()`
  * @author Teddy Katz
  */
 
@@ -15,7 +15,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'disallow unnecessary calls to sourceCode.getFirstToken and sourceCode.getLastToken',
+      description: 'disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()`',
       category: 'Rules',
       recommended: true,
     },
@@ -33,7 +33,7 @@ module.exports = {
     /**
      * Determines whether a second argument to getFirstToken or getLastToken changes the output of the function.
      * This occurs when the second argument exists and is not an object literal, or has keys other than `includeComments`.
-     * @param {ASTNode} arg The second argument to `sourceCode.getFirstToken` or `sourceCode.getLastToken`
+     * @param {ASTNode} arg The second argument to `sourceCode.getFirstToken()` or `sourceCode.getLastToken()`
      * @returns {boolean} `true` if the argument affects the output of getFirstToken or getLastToken
      */
     function affectsGetTokenOutput (arg) {

lib/rules/prefer-object-rule.js

@@ -14,7 +14,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'disallow rule exports where the export is a function.',
+      description: 'disallow rule exports where the export is a function',
       category: 'Rules',
       recommended: false,
     },

lib/rules/prefer-output-null.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview disallows invalid RuleTester test cases with the output the same as the code.
+ * @fileoverview disallows invalid RuleTester test cases where the `output` matches the `code`
  * @author 薛定谔的猫<[email protected]>
  */
 
@@ -15,7 +15,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'disallow invalid RuleTester test cases with the output the same as the code.',
+      description: 'disallow invalid RuleTester test cases where the `output` matches the `code`',
       category: 'Tests',
       recommended: false,
     },

lib/rules/prefer-placeholders.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview disallow template literals as report messages
+ * @fileoverview require using placeholders for dynamic report messages
  * @author Teddy Katz
  */
 
@@ -16,7 +16,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'disallow template literals as report messages',
+      description: 'require using placeholders for dynamic report messages',
       category: 'Rules',
       recommended: false,
     },

lib/rules/prefer-replace-text.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview prefer using replaceText instead of replaceTextRange.
+ * @fileoverview prefer using `replaceText()` instead of `replaceTextRange()`
  * @author 薛定谔的猫<[email protected]>
  */
 
@@ -15,7 +15,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'require using replaceText instead of replaceTextRange.',
+      description: 'require using `replaceText()` instead of `replaceTextRange()`',
       category: 'Rules',
       recommended: false,
     },

lib/rules/require-meta-docs-description.js

@@ -13,7 +13,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'require rules to implement a meta.docs.description property with the correct format',
+      description: 'require rules to implement a `meta.docs.description` property with the correct format',
       category: 'Rules',
       recommended: false, // TODO: enable it in a major release.
     },

lib/rules/require-meta-docs-url.js

@@ -19,7 +19,7 @@ module.exports = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'require rules to implement a meta.docs.url property',
+      description: 'require rules to implement a `meta.docs.url` property',
       category: 'Rules',
       recommended: false,
     },

lib/rules/require-meta-fixable.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview require rules to implement a meta.fixable property
+ * @fileoverview require rules to implement a `meta.fixable` property
  * @author Teddy Katz
  */
 
@@ -15,7 +15,7 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'require rules to implement a meta.fixable property',
+      description: 'require rules to implement a `meta.fixable` property',
       category: 'Rules',
       recommended: true,
     },