Merge pull request #318 from brettz9/check-examples-settings-to-options

`check-examples`: change settings to options

Author: brettz9

.README/README.md

@@ -315,91 +315,6 @@ how the keys of `preferredTypes` may have `<>` or `.<>` (or just `.`)
 appended and its bearing on whether types are checked as parents/children
 only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
 
-### Settings to Configure `check-examples`
-
-The settings below all impact the `check-examples` rule and default to
-no-op/false except as noted.
-
-JSDoc specs use of an optional `<caption>` element at the beginning of
-`@example`. The following setting requires its use.
-
-* `settings.jsdoc.captionRequired` - Require `<caption>` at beginning
-  of any `@example`
-
-JSDoc does not specify a formal means for delimiting code blocks within
-`@example` (it uses generic syntax highlighting techniques for its own
-syntax highlighting). The following settings determine whether a given
-`@example` tag will have the `check-examples` checks applied to it:
-
-* `settings.jsdoc.exampleCodeRegex` - Regex which whitelists lintable
-  examples. If a parenthetical group is used, the first one will be used,
-  so you may wish to use `(?:...)` groups where you do not wish the
-  first such group treated as one to include. If no parenthetical group
-  exists or matches, the whole matching expression will be used.
-  An example might be ````"^```(?:js|javascript)([\\s\\S]*)```$"````
-  to only match explicitly fenced JavaScript blocks.
-* `settings.jsdoc.rejectExampleCodeRegex` - Regex blacklist which rejects
-  non-lintable examples (has priority over `exampleCodeRegex`). An example
-  might be ```"^`"``` to avoid linting fenced blocks which may indicate
-  a non-JavaScript language.
-
-If neither is in use, all examples will be matched. Note also that even if
-`settings.jsdoc.captionRequired` is not set, any initial `<caption>`
-will be stripped out before doing the regex matching.
-
-The following settings determine which individual ESLint rules will be
-applied to the JavaScript found within the `@example` tags (as determined
-to be applicable by the above regex settings). They are ordered by
-decreasing precedence:
-
-* `settings.jsdoc.allowInlineConfig` - If not set to `false`, will allow
-  inline config within the `@example` to override other config. Defaults
-  to `true`.
-* `settings.jsdoc.noDefaultExampleRules` - Setting to `true` will disable the
-  default rules which are expected to be troublesome for most documentation
-  use. See the section below for the specific default rules.
-* `settings.jsdoc.matchingFileName` - Setting for a dummy file name to trigger
-  specific rules defined in one's config; usable with ESLint `.eslintrc.*`
-  `overrides` -> `files` globs, to apply a desired subset of rules with
-  `@example` (besides allowing for rules specific to examples, this setting
-  can be useful for enabling reuse of the same rules within `@example` as
-  with JavaScript Markdown lintable by
-  [other plugins](https://github.com/eslint/eslint-plugin-markdown), e.g.,
-  if one sets `matchingFileName` to `dummy.md` so that `@example` rules will
-  follow one's Markdown rules). Note that this option may come at somewhat
-  of a performance penalty as the file's existence is checked by eslint.
-* `settings.jsdoc.configFile` - A config file. Corresponds to ESLint's `-c`.
-* `settings.jsdoc.eslintrcForExamples` - Defaults to `true` in adding rules
-  based on an `.eslintrc.*` file. Setting to `false` corresponds to
-  ESLint's `--no-eslintrc`.
-* `settings.jsdoc.baseConfig` - An object of rules with the same schema
-  as `.eslintrc.*` for defaults
-
-Finally, the following rule pertains to inline disable directives:
-
-- `settings.jsdoc.reportUnusedDisableDirectives` - If not set to `false`,
-  this will report disabled directives which are not used (and thus not
-  needed). Defaults to `true`. Corresponds to ESLint's
-  `--report-unused-disable-directives`.
-
-#### Rules Disabled by Default Unless `noDefaultExampleRules` is Set to `true`
-
-* `eol-last` - Insisting that a newline "always" be at the end is less likely
-  to be desired in sample code as with the code file convention
-* `no-console` - Unlikely to have inadvertent temporary debugging within
-  examples
-* `no-undef` - Many variables in examples will be `undefined`.
-* `no-unused-vars` - It is common to define variables for clarity without always
-  using them within examples.
-* `padded-blocks` - It can generally look nicer to pad a little even if one's
-  code follows more stringency as far as block padding.
-* `import/no-unresolved` - One wouldn't generally expect example paths to
-  resolve relative to the current JavaScript file as one would with real code.
-* `import/unambiguous` - Snippets in examples are likely too short to always
-  include full import/export info
-* `node/no-missing-import` - See `import/no-unresolved`
-* `node/no-missing-require` -  See `import/no-unresolved`
-
 ## Rules
 
 {"gitdown": "include", "file": "./rules/check-alignment.md"}

.README/rules/check-examples.md

@@ -2,28 +2,104 @@
 
 Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.
 
-Works in conjunction with the following settings:
-
-* `captionRequired`
-* `exampleCodeRegex`
-* `rejectExampleCodeRegex`
-* `allowInlineConfig` - Defaults to `true`
-* `noDefaultExampleRules`
-* `matchingFileName`
-* `configFile`
-* `eslintrcForExamples` - Defaults to `true`
-* `baseConfig`
-* `reportUnusedDisableDirectives` - Defaults to `true`
+### Options
+
+The options below all default to no-op/`false` except as noted.
+
+#### `captionRequired`
+
+JSDoc specs use of an optional `<caption>` element at the beginning of
+`@example`.
+
+The option `captionRequired` insists on a `<caption>` being present at
+the beginning of any `@example`.
+
+#### `exampleCodeRegex` and `rejectExampleCodeRegex`
+
+JSDoc does not specify a formal means for delimiting code blocks within
+`@example` (it uses generic syntax highlighting techniques for its own
+syntax highlighting). The following options determine whether a given
+`@example` tag will have the `check-examples` checks applied to it:
+
+* `exampleCodeRegex` - Regex which whitelists lintable
+  examples. If a parenthetical group is used, the first one will be used,
+  so you may wish to use `(?:...)` groups where you do not wish the
+  first such group treated as one to include. If no parenthetical group
+  exists or matches, the whole matching expression will be used.
+  An example might be ````"^```(?:js|javascript)([\\s\\S]*)```$"````
+  to only match explicitly fenced JavaScript blocks.
+* `rejectExampleCodeRegex` - Regex blacklist which rejects
+  non-lintable examples (has priority over `exampleCodeRegex`). An example
+  might be ```"^`"``` to avoid linting fenced blocks which may indicate
+  a non-JavaScript language.
+
+If neither is in use, all examples will be matched. Note also that even if
+`captionRequired` is not set, any initial `<caption>` will be stripped out
+before doing the regex matching.
+
+#### `reportUnusedDisableDirectives`
+
+If not set to `false`, `reportUnusedDisableDirectives` will report disabled
+directives which are not used (and thus not needed). Defaults to `true`.
+Corresponds to ESLint's [`--report-unused-disable-directives`](https://eslint.org/docs/user-guide/command-line-interface#--report-unused-disable-directives).
 
 Inline ESLint config within `@example` JavaScript is allowed, though the
 disabling of ESLint directives which are not needed by the resolved rules
 will be reported as with the ESLint `--report-unused-disable-directives`
 command.
 
+#### Options for Determining ESLint Rule Applicability (`allowInlineConfig`, `noDefaultExampleRules`, `matchingFileName`, `configFile`, `eslintrcForExamples`, and `baseConfig`)
+
+The following options determine which individual ESLint rules will be
+applied to the JavaScript found within the `@example` tags (as determined
+to be applicable by the above regex options). They are ordered by
+decreasing precedence:
+
+* `allowInlineConfig` - If not set to `false`, will allow
+  inline config within the `@example` to override other config. Defaults
+  to `true`.
+* `noDefaultExampleRules` - Setting to `true` will disable the
+  default rules which are expected to be troublesome for most documentation
+  use. See the section below for the specific default rules.
+* `matchingFileName` - Option for a file name (even non-existent) to trigger
+  specific rules defined in one's config; usable with ESLint `.eslintrc.*`
+  `overrides` -> `files` globs, to apply a desired subset of rules with
+  `@example` (besides allowing for rules specific to examples, this option
+  can be useful for enabling reuse of the same rules within `@example` as
+  with JavaScript Markdown lintable by
+  [other plugins](https://github.com/eslint/eslint-plugin-markdown), e.g.,
+  if one sets `matchingFileName` to `dummy.md` so that `@example` rules will
+  follow one's Markdown rules). Note that this option may come at somewhat
+  of a performance penalty as the file's existence is checked by eslint.
+* `configFile` - A config file. Corresponds to ESLint's [`-c`](https://eslint.org/docs/user-guide/command-line-interface#-c---config).
+* `eslintrcForExamples` - Defaults to `true` in adding rules
+  based on an `.eslintrc.*` file. Setting to `false` corresponds to
+  ESLint's [`--no-eslintrc`](https://eslint.org/docs/user-guide/command-line-interface#--no-eslintrc).
+* `baseConfig` - An object of rules with the same schema
+  as `.eslintrc.*` for defaults
+
+##### Rules Disabled by Default Unless `noDefaultExampleRules` is Set to `true`
+
+* `eol-last` - Insisting that a newline "always" be at the end is less likely
+  to be desired in sample code as with the code file convention
+* `no-console` - Unlikely to have inadvertent temporary debugging within
+  examples
+* `no-undef` - Many variables in examples will be `undefined`.
+* `no-unused-vars` - It is common to define variables for clarity without always
+  using them within examples.
+* `padded-blocks` - It can generally look nicer to pad a little even if one's
+  code follows more stringency as far as block padding.
+* `import/no-unresolved` - One wouldn't generally expect example paths to
+  resolve relative to the current JavaScript file as one would with real code.
+* `import/unambiguous` - Snippets in examples are likely too short to always
+  include full import/export info
+* `node/no-missing-import` - See `import/no-unresolved`
+* `node/no-missing-require` -  See `import/no-unresolved`
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `ClassDeclaration`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`example`|
-|Settings| *See above* |
+|Options| *See above* |
 
 <!-- assertions checkExamples -->