Docs: ensure rule doc titles match rule descriptions (#147)

bmish · web-flow · commit c55a95616dd2 · 2021-06-26T04:13:35.000+08:00
* Start rule doc titles with a capital letter
* Test to ensure rule doc titles include the description from rule.meta.docs.description
diff --git a/docs/rules/meta-property-ordering.md b/docs/rules/meta-property-ordering.md
@@ -1,4 +1,4 @@
-# enforce ordering of meta properties in rule source (meta-property-ordering)
+# Enforce the order of meta properties (meta-property-ordering)
 
 ⚒️ 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.
 
diff --git a/docs/rules/no-deprecated-context-methods.md b/docs/rules/no-deprecated-context-methods.md
@@ -1,4 +1,4 @@
-# Disallows usage of deprecated methods on rule context objects (no-deprecated-context-methods)
+# Disallow usage of deprecated methods on rule context objects (no-deprecated-context-methods)
 
 ⚒️ 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.
 
diff --git a/docs/rules/no-deprecated-report-api.md b/docs/rules/no-deprecated-report-api.md
@@ -1,4 +1,4 @@
-# disallow use of the deprecated context.report() API (no-deprecated-report-api)
+# Disallow use of the deprecated context.report() API (no-deprecated-report-api)
 
 ✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.
 
diff --git a/docs/rules/prefer-output-null.md b/docs/rules/prefer-output-null.md
@@ -1,4 +1,4 @@
-# Disallows invalid RuleTester test cases with the output the same as the code. (prefer-output-null)
+# Disallow invalid RuleTester test cases with the output the same as 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.
 
diff --git a/docs/rules/prefer-placeholders.md b/docs/rules/prefer-placeholders.md
@@ -1,4 +1,4 @@
-# disallow template literals as report messages (prefer-placeholders)
+# Disallow template literals as report messages (prefer-placeholders)
 
 Report messages in rules can have placeholders surrounded by curly brackets.
 
diff --git a/docs/rules/prefer-replace-text.md b/docs/rules/prefer-replace-text.md
@@ -1,4 +1,4 @@
-# prefer using replaceText instead of replaceTextRange. (prefer-replace-text)
+# Require using replaceText instead of replaceTextRange. (prefer-replace-text)
 
 ## Rule Details
 
diff --git a/docs/rules/report-message-format.md b/docs/rules/report-message-format.md
@@ -1,4 +1,4 @@
-# enforce a consistent format for rule report messages (report-message-format)
+# Enforce a consistent format for rule report messages (report-message-format)
 
 It is sometimes desirable to maintain consistent formatting for all report messages. For example, you might want to mandate that all report messages begin with a capital letter and end with a period.
 
diff --git a/docs/rules/require-meta-docs-description.md b/docs/rules/require-meta-docs-description.md
@@ -1,4 +1,4 @@
-# require rules to implement a meta.docs.description property (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.
 
diff --git a/docs/rules/require-meta-docs-url.md b/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.
 
diff --git a/docs/rules/require-meta-fixable.md b/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.
 
diff --git a/docs/rules/require-meta-has-suggestions.md b/docs/rules/require-meta-has-suggestions.md
@@ -1,4 +1,4 @@
-# require suggestable rules to implement a `meta.hasSuggestions` property (require-meta-has-suggestions)
+# Require suggestable rules to implement a `meta.hasSuggestions` property (require-meta-has-suggestions)
 
 A suggestable ESLint rule should specify the `meta.hasSuggestions` property with a value of `true`. This makes it easier for both humans and tooling to tell whether a rule provides suggestions. [As of ESLint 8](https://eslint.org/blog/2021/06/whats-coming-in-eslint-8.0.0#rules-with-suggestions-now-require-the-metahassuggestions-property), an exception will be thrown if a suggestable rule is missing this property.
 
diff --git a/docs/rules/require-meta-schema.md b/docs/rules/require-meta-schema.md
@@ -1,8 +1,8 @@
-# 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.
 
-Defining a schema for each rule allows eslint to validate that configuration options are passed correctly. Even when there are no options for a rule, a schema should still be defined (as an empty array) so that eslint can validate that no data is passed to the rule.
+Defining a schema for each rule allows eslint to validate that configuration options are passed correctly. Even when there are no options for a rule, a schema should still be defined (as an empty array) so that eslint can validate that no data is mistakenly passed to the rule.
 
 ## Rule Details
 
diff --git a/docs/rules/require-meta-type.md b/docs/rules/require-meta-type.md
@@ -1,4 +1,4 @@
-# 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`.
 
diff --git a/docs/rules/test-case-property-ordering.md b/docs/rules/test-case-property-ordering.md
@@ -1,4 +1,4 @@
-# enforce ordering of keys in test cases (test-case-property-ordering)
+# Require the properties of a test case to be placed in a consistent order (test-case-property-ordering)
 
 ⚒️ 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.
 
diff --git a/tests/lib/rule-setup.js b/tests/lib/rule-setup.js
@@ -16,6 +16,14 @@ const MESSAGES = {
   hasSuggestions: '💡 Some problems reported by this rule are manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).',
 };
 
+/**
+ * @param {string} string - to operate on
+ * @returns the string with a capitalized first letter
+ */
+function capitalizeFirstLetter (string) {
+  return string.charAt(0).toUpperCase() + string.slice(1);
+}
+
 describe('rule setup is correct', () => {
   it('should have a list of exported rules and rules directory that match', () => {
     const filePath = path.join(__dirname, '..', 'lib', 'rules');
@@ -70,7 +78,7 @@ describe('rule setup is correct', () => {
       describe(ruleName, () => {
         it('should have the right contents (title, notices, etc)', () => {
           // Title
-          assert.ok(lines[0].endsWith(`(${ruleName})`), 'first line ends with rule name');
+          assert.strictEqual(lines[0], `# ${capitalizeFirstLetter(rule.meta.docs.description)} (${ruleName})`, 'first line has rule description and name');
           assert.strictEqual(lines[1], '', 'second line is blank');
 
           // Rule Details

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# enforce ordering of meta properties in rule source (meta-property-ordering)`
	`1`	`+# Enforce the order of meta properties (meta-property-ordering)`
`2`	`2`
`3`	`3`	⚒️ 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.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Disallows usage of deprecated methods on rule context objects (no-deprecated-context-methods)`
	`1`	`+# Disallow usage of deprecated methods on rule context objects (no-deprecated-context-methods)`
`2`	`2`
`3`	`3`	⚒️ 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.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# disallow use of the deprecated context.report() API (no-deprecated-report-api)`
	`1`	`+# Disallow use of the deprecated context.report() API (no-deprecated-report-api)`
`2`	`2`
`3`	`3`	✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Disallows invalid RuleTester test cases with the output the same as the code. (prefer-output-null)`
	`1`	`+# Disallow invalid RuleTester test cases with the output the same as the code. (prefer-output-null)`
`2`	`2`
`3`	`3`	⚒️ 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.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# disallow template literals as report messages (prefer-placeholders)`
	`1`	`+# Disallow template literals as report messages (prefer-placeholders)`
`2`	`2`
`3`	`3`	`Report messages in rules can have placeholders surrounded by curly brackets.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# prefer using replaceText instead of replaceTextRange. (prefer-replace-text)`
	`1`	`+# Require using replaceText instead of replaceTextRange. (prefer-replace-text)`
`2`	`2`
`3`	`3`	`## Rule Details`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# enforce a consistent format for rule report messages (report-message-format)`
	`1`	`+# Enforce a consistent format for rule report messages (report-message-format)`
`2`	`2`
`3`	`3`	`It is sometimes desirable to maintain consistent formatting for all report messages. For example, you might want to mandate that all report messages begin with a capital letter and end with a period.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# require rules to implement a meta.docs.description property (require-meta-docs-description)`
	`1`	`+# Require rules to implement a meta.docs.description property with the correct format (require-meta-docs-description)`
`2`	`2`
`3`	`3`	`Defining a clear and consistent description for each rule helps developers understand what they're used for.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# require rules to implement a meta.fixable property (require-meta-fixable)`
	`1`	`+# Require rules to implement a meta.fixable property (require-meta-fixable)`
`2`	`2`
`3`	`3`	✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.
`4`	`4`