docs: Disallow multiple rule configuration comments in the same examp…

…le (#18116)

docs/src/rules/func-name-matching.md

@@ -54,8 +54,7 @@ Examples of **correct** code for this rule:
 
 ```js
 /*eslint func-name-matching: "error"*/
-/*eslint func-name-matching: ["error", "always"]*/ // these are equivalent
-/*eslint-env es6*/
+// equivalent to /*eslint func-name-matching: ["error", "always"]*/
 
 var foo = function foo() {};
 var foo = function() {};
@@ -157,7 +156,7 @@ Examples of **correct** code for the `{ considerPropertyDescriptor: true }` opti
 
 ```js
 /*eslint func-name-matching: ["error", { "considerPropertyDescriptor": true }]*/
-/*eslint func-name-matching: ["error", "always", { "considerPropertyDescriptor": true }]*/ // these are equivalent
+// equivalent to /*eslint func-name-matching: ["error", "always", { "considerPropertyDescriptor": true }]*/
 var obj = {};
 Object.create(obj, {foo:{value: function foo() {}}});
 Object.defineProperty(obj, 'bar', {value: function bar() {}});
@@ -173,7 +172,7 @@ Examples of **incorrect** code for the `{ considerPropertyDescriptor: true }` op
 
 ```js
 /*eslint func-name-matching: ["error", { "considerPropertyDescriptor": true }]*/
-/*eslint func-name-matching: ["error", "always", { "considerPropertyDescriptor": true }]*/ // these are equivalent
+// equivalent to /*eslint func-name-matching: ["error", "always", { "considerPropertyDescriptor": true }]*/
 var obj = {};
 Object.create(obj, {foo:{value: function bar() {}}});
 Object.defineProperty(obj, 'bar', {value: function baz() {}});
@@ -193,7 +192,7 @@ Examples of **incorrect** code for the `{ includeCommonJSModuleExports: true }`
 
 ```js
 /*eslint func-name-matching: ["error", { "includeCommonJSModuleExports": true }]*/
-/*eslint func-name-matching: ["error", "always", { "includeCommonJSModuleExports": true }]*/ // these are equivalent
+// equivalent to /*eslint func-name-matching: ["error", "always", { "includeCommonJSModuleExports": true }]*/
 
 module.exports = function foo(name) {};
 module['exports'] = function foo(name) {};

docs/src/rules/lines-around-comment.md

@@ -653,9 +653,9 @@ const [
 
 ### ignorePattern
 
-By default this rule ignores comments starting with the following words: `eslint`, `jshint`, `jslint`, `istanbul`, `global`, `exported`, `jscs`. To ignore more comments in addition to the defaults, set the `ignorePattern` option to a string pattern that will be passed to the [`RegExp` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp).
+By default this rule ignores comments starting with the following words: `eslint`, `jshint`, `jslint`, `istanbul`, `global`, `exported`, `jscs`.
 
-Examples of **correct** code for the `ignorePattern` option:
+Examples of **correct** code for this rule:
 
 ::: correct
 
@@ -665,9 +665,23 @@ Examples of **correct** code for the `ignorePattern` option:
 foo();
 /* jshint mentioned in this comment */
 bar();
+```
+
+:::
+
+To ignore more comments in addition to the defaults, set the `ignorePattern` option to a string pattern that will be passed to the [`RegExp` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp).
+
+Examples of **correct** code for the `ignorePattern` option:
 
+::: correct
+
+```js
 /*eslint lines-around-comment: ["error", { "ignorePattern": "pragma" }] */
 
+foo();
+/* jshint mentioned in this comment */
+bar();
+
 foo();
 /* a valid comment using pragma in it */
 ```

tests/fixtures/bad-examples.md

@@ -42,3 +42,13 @@ const foo = "baz";
 ```
 
 :::
+
+:::correct
+
+```js
+/* eslint no-restricted-syntax: "error" */
+
+/* eslint no-restricted-syntax: ["error", "ArrayPattern"] */
+```
+
+:::

tests/tools/check-rule-examples.js

@@ -77,8 +77,9 @@ describe("check-rule-examples", () => {
                 "\x1B[0m  \x1B[2m23:7\x1B[22m  \x1B[31merror\x1B[39m  Syntax error: Identifier 'foo' has already been declared\x1B[0m\n" +
                 "\x1B[0m  \x1B[2m31:1\x1B[22m  \x1B[31merror\x1B[39m  Example code should contain a configuration comment like /* eslint no-restricted-syntax: \"error\" */\x1B[0m\n" +
                 "\x1B[0m  \x1B[2m41:1\x1B[22m  \x1B[31merror\x1B[39m  Failed to parse JSON from ' doesn't allow this comment'\x1B[0m\n" +
+                "\x1B[0m  \x1B[2m51:1\x1B[22m  \x1B[31merror\x1B[39m  Duplicate /* eslint no-restricted-syntax */ configuration comment. Each example should contain only one. Split this example into multiple examples\x1B[0m\n" +
                 "\x1B[0m\x1B[0m\n" +
-                "\x1B[0m\x1B[31m\x1B[1m✖ 6 problems (6 errors, 0 warnings)\x1B[22m\x1B[39m\x1B[0m\n" +
+                "\x1B[0m\x1B[31m\x1B[1m✖ 7 problems (7 errors, 0 warnings)\x1B[22m\x1B[39m\x1B[0m\n" +
                 "\x1B[0m\x1B[31m\x1B[1m\x1B[22m\x1B[39m\x1B[0m\n";
 
                 assert.strictEqual(normalizedStderr, expectedStderr);

tools/check-rule-examples.js

@@ -96,6 +96,15 @@ async function findProblems(filename) {
                         parseError.line += codeBlockToken.map[0] + 1;
                         problems.push(parseError);
                     } else if (Object.hasOwn(parseResult.config, title)) {
+                        if (hasRuleConfigComment) {
+                            problems.push({
+                                fatal: false,
+                                severity: 2,
+                                message: `Duplicate /* eslint ${title} */ configuration comment. Each example should contain only one. Split this example into multiple examples.`,
+                                line: codeBlockToken.map[0] + 1 + comment.loc.start.line,
+                                column: comment.loc.start.column + 1
+                            });
+                        }
                         hasRuleConfigComment = true;
                     }
                 }