Skip to content

Latest commit

 

History

History
123 lines (100 loc) · 5.59 KB

check-examples.md

File metadata and controls

123 lines (100 loc) · 5.59 KB
Raw

check-examples

Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.

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]*)```\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.

paddedIndent

This integer property allows one to add a fixed amount of whitespace at the beginning of the second or later lines of the example to be stripped so as to avoid linting issues with the decorative whitespace. For example, if set to a value of 4, the initial whitespace below will not trigger indent rule errors as the extra 4 spaces on each subsequent line will be stripped out before evaluation.

/**
 * @example
 *     anArray.filter((a) => {
 *      return a.b;
 *     });
 */

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.

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, 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.
  • eslintrcForExamples - Defaults to true in adding rules based on an .eslintrc.* file. Setting to false corresponds to ESLint's --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 everywhere
Tags example
Options See above