Skip to content

Commit

Permalink
Merge pull request #318 from brettz9/check-examples-settings-to-options
Browse files Browse the repository at this point in the history 
`check-examples`: change settings to options
  • Loading branch information
@brettz9
brettz9 committed Jul 7, 2019
2 parents f44b25e + c4f221d commit 9c9429e
Show file tree
Hide file tree
Showing 7 changed files with 526 additions and 454 deletions.
85 changes: 0 additions & 85 deletions .README/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"}
Expand Down
102 changes: 89 additions & 13 deletions .README/rules/check-examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->

0 comments on commit 9c9429e

Please sign in to comment.