Skip to content

Commit 5a85f0f

Browse files
brettz9brettz9
committed
refactoring(check-examples): rename eslintrcForExamples to checkEslintrc; also ensure matchingFileName always triggers config retrieval
BREAKING CHANGE: This commit also clarifies new precedence and behavior in docs.
1 parent 3ac6c8d commit 5a85f0f

File tree

5 files changed

+106
-82
lines changed

5 files changed

+106
-82
lines changed

‎.README/rules/check-examples.md

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ disabling of ESLint directives which are not needed by the resolved rules
7171
will be reported as with the ESLint `--report-unused-disable-directives`
7272
command.
7373

74-
#### Options for Determining ESLint Rule Applicability (`allowInlineConfig`, `noDefaultExampleRules`, `matchingFileName`, `configFile`, `eslintrcForExamples`, and `baseConfig`)
74+
#### Options for Determining ESLint Rule Applicability (`allowInlineConfig`, `noDefaultExampleRules`, `matchingFileName`, `configFile`, `checkEslintrc`, and `baseConfig`)
7575

7676
The following options determine which individual ESLint rules will be
7777
applied to the JavaScript found within the `@example` tags (as determined
@@ -84,6 +84,7 @@ decreasing precedence:
8484
* `noDefaultExampleRules` - Setting to `true` will disable the
8585
default rules which are expected to be troublesome for most documentation
8686
use. See the section below for the specific default rules.
87+
* `configFile` - A config file. Corresponds to ESLint's [`-c`](https://eslint.org/docs/user-guide/command-line-interface#-c---config).
8788
* `matchingFileName` - Option for a file name (even non-existent) to trigger
8889
specific rules defined in one's config; usable with ESLint `.eslintrc.*`
8990
`overrides` -> `files` globs, to apply a desired subset of rules with
@@ -92,12 +93,22 @@ decreasing precedence:
9293
with JavaScript Markdown lintable by
9394
[other plugins](https://github.com/eslint/eslint-plugin-markdown), e.g.,
9495
if one sets `matchingFileName` to `dummy.md` so that `@example` rules will
95-
follow one's Markdown rules). Note that this option may come at somewhat
96-
of a performance penalty as the file's existence is checked by eslint.
97-
* `configFile` - A config file. Corresponds to ESLint's [`-c`](https://eslint.org/docs/user-guide/command-line-interface#-c---config).
98-
* `eslintrcForExamples` - Defaults to `true` in adding rules
96+
follow one's Markdown rules).
97+
* `checkEslintrc` - Defaults to `true` in adding rules
9998
based on an `.eslintrc.*` file. Setting to `false` corresponds to
10099
ESLint's [`--no-eslintrc`](https://eslint.org/docs/user-guide/command-line-interface#--no-eslintrc).
100+
If `matchingFileName` is set, this will automatically be `true` and
101+
will use the config corresponding to that file. If `matchingFileName` is
102+
not set and this value is set to `false`, the `.eslintrc.*` configs will
103+
not be checked. If `matchingFileName` is not set, and this is unset or
104+
set to `true`, the `.eslintrc.*` configs will be checked as though the file
105+
name were the same as the file containing the example, with any file
106+
extension changed to ".md" (and if there is no file extension, "dummy.md"
107+
will be used). This allows convenient sharing of similar rules with often
108+
also context-free Markdown as well as use of `overrides` as described under
109+
`matchingFileName`. Note that this option (whether set by `matchingFileName`
110+
or set manually to `true`) may come at somewhat of a performance penalty
111+
as the file's existence is checked by eslint.
101112
* `baseConfig` - Set to an object of rules with the same schema
102113
as `.eslintrc.*` for defaults.
103114

‎README.md

Lines changed: 49 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -779,8 +779,8 @@ disabling of ESLint directives which are not needed by the resolved rules
779779
will be reported as with the ESLint `--report-unused-disable-directives`
780780
command.
781781

782-
<a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-eslintrcforexamples-and-baseconfig"></a>
783-
#### Options for Determining ESLint Rule Applicability (<code>allowInlineConfig</code>, <code>noDefaultExampleRules</code>, <code>matchingFileName</code>, <code>configFile</code>, <code>eslintrcForExamples</code>, and <code>baseConfig</code>)
782+
<a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig"></a>
783+
#### Options for Determining ESLint Rule Applicability (<code>allowInlineConfig</code>, <code>noDefaultExampleRules</code>, <code>matchingFileName</code>, <code>configFile</code>, <code>checkEslintrc</code>, and <code>baseConfig</code>)
784784

785785
The following options determine which individual ESLint rules will be
786786
applied to the JavaScript found within the `@example` tags (as determined
@@ -793,6 +793,7 @@ decreasing precedence:
793793
* `noDefaultExampleRules` - Setting to `true` will disable the
794794
default rules which are expected to be troublesome for most documentation
795795
use. See the section below for the specific default rules.
796+
* `configFile` - A config file. Corresponds to ESLint's [`-c`](https://eslint.org/docs/user-guide/command-line-interface#-c---config).
796797
* `matchingFileName` - Option for a file name (even non-existent) to trigger
797798
specific rules defined in one's config; usable with ESLint `.eslintrc.*`
798799
`overrides` -> `files` globs, to apply a desired subset of rules with
@@ -801,16 +802,26 @@ decreasing precedence:
801802
with JavaScript Markdown lintable by
802803
[other plugins](https://github.com/eslint/eslint-plugin-markdown), e.g.,
803804
if one sets `matchingFileName` to `dummy.md` so that `@example` rules will
804-
follow one's Markdown rules). Note that this option may come at somewhat
805-
of a performance penalty as the file's existence is checked by eslint.
806-
* `configFile` - A config file. Corresponds to ESLint's [`-c`](https://eslint.org/docs/user-guide/command-line-interface#-c---config).
807-
* `eslintrcForExamples` - Defaults to `true` in adding rules
805+
follow one's Markdown rules).
806+
* `checkEslintrc` - Defaults to `true` in adding rules
808807
based on an `.eslintrc.*` file. Setting to `false` corresponds to
809808
ESLint's [`--no-eslintrc`](https://eslint.org/docs/user-guide/command-line-interface#--no-eslintrc).
809+
If `matchingFileName` is set, this will automatically be `true` and
810+
will use the config corresponding to that file. If `matchingFileName` is
811+
not set and this value is set to `false`, the `.eslintrc.*` configs will
812+
not be checked. If `matchingFileName` is not set, and this is unset or
813+
set to `true`, the `.eslintrc.*` configs will be checked as though the file
814+
name were the same as the file containing the example, with any file
815+
extension changed to ".md" (and if there is no file extension, "dummy.md"
816+
will be used). This allows convenient sharing of similar rules with often
817+
also context-free Markdown as well as use of `overrides` as described under
818+
`matchingFileName`. Note that this option (whether set by `matchingFileName`
819+
or set manually to `true`) may come at somewhat of a performance penalty
820+
as the file's existence is checked by eslint.
810821
* `baseConfig` - Set to an object of rules with the same schema
811822
as `.eslintrc.*` for defaults.
812823

813-
<a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-eslintrcforexamples-and-baseconfig-rules-disabled-by-default-unless-nodefaultexamplerules-is-set-to-true"></a>
824+
<a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig-rules-disabled-by-default-unless-nodefaultexamplerules-is-set-to-true"></a>
814825
##### Rules Disabled by Default Unless <code>noDefaultExampleRules</code> is Set to <code>true</code>
815826

816827
* `eol-last` - Insisting that a newline "always" be at the end is less likely
@@ -848,7 +859,7 @@ The following patterns are considered problems:
848859
function quux () {
849860

850861
}
851-
// Options: [{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"eslintrcForExamples":false}]
862+
// Options: [{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"checkEslintrc":false}]
852863
// Message: @example error (no-alert): Unexpected alert.
853864

854865
/**
@@ -857,7 +868,7 @@ function quux () {
857868
class quux {
858869

859870
}
860-
// Options: [{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"eslintrcForExamples":false}]
871+
// Options: [{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"checkEslintrc":false}]
861872
// Message: @example error (no-alert): Unexpected alert.
862873

863874
/**
@@ -868,7 +879,7 @@ class quux {
868879
function quux () {
869880

870881
}
871-
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}]
882+
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}]
872883
// Message: @example error (semi): Extra semicolon.
873884

874885
/**
@@ -879,7 +890,7 @@ function quux () {
879890
function quux () {
880891

881892
}
882-
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}]
893+
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}]
883894
// Message: @example error (semi): Extra semicolon.
884895

885896
/**
@@ -889,7 +900,7 @@ function quux () {
889900
var quux = {
890901

891902
};
892-
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}]
903+
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}]
893904
// Message: @example error (semi): Extra semicolon.
894905

895906
/**
@@ -899,7 +910,7 @@ var quux = {
899910
function quux () {
900911

901912
}
902-
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```\njs ([\\s\\S]*)```"}]
913+
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```\njs ([\\s\\S]*)```"}]
903914
// Message: @example error (semi): Extra semicolon.
904915

905916
/**
@@ -914,7 +925,7 @@ function quux () {
914925
function quux2 () {
915926

916927
}
917-
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"rejectExampleCodeRegex":"^\\s*<.*>\\s*$"}]
928+
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"rejectExampleCodeRegex":"^\\s*<.*>\\s*$"}]
918929
// Message: @example error (semi): Extra semicolon.
919930

920931
/**
@@ -924,7 +935,7 @@ function quux2 () {
924935
function quux () {
925936

926937
}
927-
// Options: [{"baseConfig":{"rules":{"no-undef":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}]
938+
// Options: [{"baseConfig":{"rules":{"no-undef":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":true}]
928939
// Message: @example error (no-undef): 'quux' is not defined.
929940

930941
/**
@@ -937,7 +948,7 @@ function quux () {
937948
function quux () {
938949

939950
}
940-
// Options: [{"captionRequired":true,"eslintrcForExamples":false}]
951+
// Options: [{"captionRequired":true,"checkEslintrc":false}]
941952
// Message: Caption is expected for examples.
942953

943954
/**
@@ -946,22 +957,22 @@ function quux () {
946957
function quux () {
947958

948959
}
949-
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}]
960+
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
950961
// Message: @example error (indent): Expected indentation of 0 spaces but found 1.
951962

952963
/**
953964
* @example test() // eslint-disable-line semi
954965
*/
955966
function quux () {}
956-
// Options: [{"eslintrcForExamples":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":true}]
967+
// Options: [{"checkEslintrc":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":true}]
957968
// Message: @example error: Unused eslint-disable directive (no problems were reported from 'semi').
958969

959970
/**
960971
* @example
961972
test() // eslint-disable-line semi
962973
*/
963974
function quux () {}
964-
// Options: [{"allowInlineConfig":false,"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}]
975+
// Options: [{"allowInlineConfig":false,"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"noDefaultExampleRules":true}]
965976
// Message: @example error (semi): Missing semicolon.
966977

967978
/**
@@ -1032,7 +1043,7 @@ function quux2 () {
10321043
function quux2 () {
10331044

10341045
}
1035-
// Options: [{"eslintrcForExamples":false,"matchingFileName":"dummy.js"}]
1046+
// Options: [{"checkEslintrc":false,"matchingFileName":"dummy.js"}]
10361047
// Message: @example error: Parsing error: The keyword 'const' is reserved
10371048

10381049
/**
@@ -1043,7 +1054,7 @@ function quux2 () {
10431054
function quux () {
10441055

10451056
}
1046-
// Options: [{"baseConfig":{"rules":{"semi":["warn","always"]}},"eslintrcForExamples":false,"exampleCodeRegex":"// begin[\\s\\S]*// end","noDefaultExampleRules":true}]
1057+
// Options: [{"baseConfig":{"rules":{"semi":["warn","always"]}},"checkEslintrc":false,"exampleCodeRegex":"// begin[\\s\\S]*// end","noDefaultExampleRules":true}]
10471058
// Message: @example warning (semi): Missing semicolon.
10481059

10491060
/**
@@ -1060,7 +1071,7 @@ function f () {
10601071
* @example <caption></caption>
10611072
* 'foo'
10621073
*/
1063-
// Options: [{"captionRequired":true,"eslintrcForExamples":false}]
1074+
// Options: [{"captionRequired":true,"checkEslintrc":false}]
10641075
// Message: Caption is expected for examples.
10651076

10661077
/**
@@ -1071,7 +1082,7 @@ function f () {
10711082
function quux () {
10721083

10731084
}
1074-
// Options: [{"baseConfig":{"parser":"@typescript-eslint/parser","parserOptions":{"ecmaVersion":6},"rules":{"semi":["error","always"]}},"eslintrcForExamples":false}]
1085+
// Options: [{"baseConfig":{"parser":"@typescript-eslint/parser","parserOptions":{"ecmaVersion":6},"rules":{"semi":["error","always"]}},"checkEslintrc":false}]
10751086
// Message: @example error (semi): Missing semicolon.
10761087

10771088
/**
@@ -1106,7 +1117,7 @@ function quux () {
11061117
*
11071118
* ![Screenshot](path/to/screenshot.jpg)
11081119
*/
1109-
// Options: [{"baseConfig":{"parserOptions":{"ecmaVersion":2015,"sourceType":"module"},"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"exampleCodeRegex":"/^```(?:js|javascript)\\n([\\s\\S]*?)```$/gm"}]
1120+
// Options: [{"baseConfig":{"parserOptions":{"ecmaVersion":2015,"sourceType":"module"},"rules":{"semi":["error","always"]}},"checkEslintrc":false,"exampleCodeRegex":"/^```(?:js|javascript)\\n([\\s\\S]*?)```$/gm"}]
11101121
// Message: @example error (semi): Missing semicolon.
11111122

11121123
/**
@@ -1121,7 +1132,7 @@ function quux () {
11211132
function quux () {
11221133

11231134
}
1124-
// Options: [{"baseConfig":{"rules":{"semi":["warn","always"]}},"eslintrcForExamples":false,"exampleCodeRegex":"/\\/\\/ begin[\\s\\S]*?// end/g","noDefaultExampleRules":true}]
1135+
// Options: [{"baseConfig":{"rules":{"semi":["warn","always"]}},"checkEslintrc":false,"exampleCodeRegex":"/\\/\\/ begin[\\s\\S]*?// end/g","noDefaultExampleRules":true}]
11251136
// Message: @example warning (semi): Missing semicolon.
11261137

11271138
/**
@@ -1131,7 +1142,7 @@ function quux () {
11311142
function quux () {
11321143

11331144
}
1134-
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}]
1145+
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
11351146
// Message: @example error (indent): Expected indentation of 0 spaces but found 2.
11361147
````
11371148

@@ -1146,7 +1157,7 @@ The following patterns are not considered problems:
11461157
function quux () {
11471158

11481159
}
1149-
// Options: [{"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}]
1160+
// Options: [{"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}]
11501161

11511162
/**
11521163
* @example ```js
@@ -1156,7 +1167,7 @@ function quux () {
11561167
function quux () {
11571168

11581169
}
1159-
// Options: [{"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"exampleCodeRegex":"/```js([\\s\\S]*)```/"}]
1170+
// Options: [{"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"exampleCodeRegex":"/```js([\\s\\S]*)```/"}]
11601171

11611172
/**
11621173
* @example
@@ -1165,7 +1176,7 @@ function quux () {
11651176
function quux () {
11661177

11671178
}
1168-
// Options: [{"eslintrcForExamples":false}]
1179+
// Options: [{"checkEslintrc":false}]
11691180

11701181
/**
11711182
* @example
@@ -1174,15 +1185,15 @@ function quux () {
11741185
function quux () {
11751186

11761187
}
1177-
// Options: [{"baseConfig":{"rules":{"no-undef":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}]
1188+
// Options: [{"baseConfig":{"rules":{"no-undef":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
11781189

11791190
/**
11801191
* @example quux();
11811192
*/
11821193
function quux () {
11831194

11841195
}
1185-
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}]
1196+
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
11861197

11871198
/**
11881199
* @example <caption>Valid usage</caption>
@@ -1194,20 +1205,20 @@ function quux () {
11941205
function quux () {
11951206

11961207
}
1197-
// Options: [{"captionRequired":true,"eslintrcForExamples":false}]
1208+
// Options: [{"captionRequired":true,"checkEslintrc":false}]
11981209

11991210
/**
12001211
* @example test() // eslint-disable-line semi
12011212
*/
12021213
function quux () {}
1203-
// Options: [{"eslintrcForExamples":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":false}]
1214+
// Options: [{"checkEslintrc":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":false}]
12041215

12051216
/**
12061217
* @example
12071218
test() // eslint-disable-line semi
12081219
*/
12091220
function quux () {}
1210-
// Options: [{"allowInlineConfig":true,"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}]
1221+
// Options: [{"allowInlineConfig":true,"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"noDefaultExampleRules":true}]
12111222

12121223
/**
12131224
* @example ```js
@@ -1217,7 +1228,7 @@ function quux () {}
12171228
var quux = {
12181229

12191230
};
1220-
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}]
1231+
// Options: [{"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}]
12211232

12221233
/**
12231234
* @example
@@ -1226,7 +1237,7 @@ var quux = {
12261237
* });
12271238
*/
12281239
function quux () {}
1229-
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}]
1240+
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
12301241

12311242
/**
12321243
* @example
@@ -1236,7 +1247,7 @@ function quux () {}
12361247
function quux () {
12371248

12381249
}
1239-
// Options: [{"baseConfig":{"parser":"@typescript-eslint/parser","parserOptions":{"ecmaVersion":6},"rules":{"semi":["error","always"]}},"eslintrcForExamples":false}]
1250+
// Options: [{"baseConfig":{"parser":"@typescript-eslint/parser","parserOptions":{"ecmaVersion":6},"rules":{"semi":["error","always"]}},"checkEslintrc":false}]
12401251

12411252
/**
12421253
* @example const ident = 5;
@@ -1257,7 +1268,7 @@ function quux2 () {
12571268
function quux () {
12581269

12591270
}
1260-
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}]
1271+
// Options: [{"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
12611272
````
12621273

12631274

0 commit comments

Comments
 (0)