From 2d69c7008105f23833596dedebd992f586adf5af Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Wed, 2 Mar 2022 08:14:02 +0800 Subject: [PATCH] fix: update devDeps, including gitdown to fix README URLs; fixes #707 --- README.md | 378 ++++++++++++++++++++++++++++++++++++++++----------- package.json | 12 +- 2 files changed, 302 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 03038d123..57cd0500f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # eslint-plugin-jsdoc @@ -9,72 +10,73 @@ JSDoc linting rules for ESLint. -* [eslint-plugin-jsdoc](#eslint-plugin-jsdoc) - * [Installation](#eslint-plugin-jsdoc-installation) - * [Configuration](#eslint-plugin-jsdoc-configuration) - * [Options](#eslint-plugin-jsdoc-options) - * [Settings](#eslint-plugin-jsdoc-settings) - * [Allow tags (`@private` or `@internal`) to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block) - * [`maxLines` and `minLines`](#eslint-plugin-jsdoc-settings-maxlines-and-minlines) - * [Mode](#eslint-plugin-jsdoc-settings-mode) - * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference) - * [`@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields) - * [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types) - * [`structuredTags`](#eslint-plugin-jsdoc-settings-structuredtags) - * [Advanced](#eslint-plugin-jsdoc-advanced) - * [AST and Selectors](#eslint-plugin-jsdoc-advanced-ast-and-selectors) - * [Rules](#eslint-plugin-jsdoc-rules) - * [`check-access`](#eslint-plugin-jsdoc-rules-check-access) - * [`check-alignment`](#eslint-plugin-jsdoc-rules-check-alignment) - * [`check-examples`](#eslint-plugin-jsdoc-rules-check-examples) - * [`check-indentation`](#eslint-plugin-jsdoc-rules-check-indentation) - * [`check-line-alignment`](#eslint-plugin-jsdoc-rules-check-line-alignment) - * [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names) - * [`check-property-names`](#eslint-plugin-jsdoc-rules-check-property-names) - * [`check-syntax`](#eslint-plugin-jsdoc-rules-check-syntax) - * [`check-tag-names`](#eslint-plugin-jsdoc-rules-check-tag-names) - * [`check-types`](#eslint-plugin-jsdoc-rules-check-types) - * [`check-values`](#eslint-plugin-jsdoc-rules-check-values) - * [`empty-tags`](#eslint-plugin-jsdoc-rules-empty-tags) - * [`implements-on-classes`](#eslint-plugin-jsdoc-rules-implements-on-classes) - * [`match-description`](#eslint-plugin-jsdoc-rules-match-description) - * [`match-name`](#eslint-plugin-jsdoc-rules-match-name) - * [`multiline-blocks`](#eslint-plugin-jsdoc-rules-multiline-blocks) - * [`newline-after-description`](#eslint-plugin-jsdoc-rules-newline-after-description) - * [`no-bad-blocks`](#eslint-plugin-jsdoc-rules-no-bad-blocks) - * [`no-defaults`](#eslint-plugin-jsdoc-rules-no-defaults) - * [`no-missing-syntax`](#eslint-plugin-jsdoc-rules-no-missing-syntax) - * [`no-multi-asterisks`](#eslint-plugin-jsdoc-rules-no-multi-asterisks) - * [`no-restricted-syntax`](#eslint-plugin-jsdoc-rules-no-restricted-syntax) - * [`no-types`](#eslint-plugin-jsdoc-rules-no-types) - * [`no-undefined-types`](#eslint-plugin-jsdoc-rules-no-undefined-types) - * [`require-asterisk-prefix`](#eslint-plugin-jsdoc-rules-require-asterisk-prefix) - * [`require-description-complete-sentence`](#eslint-plugin-jsdoc-rules-require-description-complete-sentence) - * [`require-description`](#eslint-plugin-jsdoc-rules-require-description) - * [`require-example`](#eslint-plugin-jsdoc-rules-require-example) - * [`require-file-overview`](#eslint-plugin-jsdoc-rules-require-file-overview) - * [`require-hyphen-before-param-description`](#eslint-plugin-jsdoc-rules-require-hyphen-before-param-description) - * [`require-jsdoc`](#eslint-plugin-jsdoc-rules-require-jsdoc) - * [`require-param-description`](#eslint-plugin-jsdoc-rules-require-param-description) - * [`require-param-name`](#eslint-plugin-jsdoc-rules-require-param-name) - * [`require-param-type`](#eslint-plugin-jsdoc-rules-require-param-type) - * [`require-param`](#eslint-plugin-jsdoc-rules-require-param) - * [`require-property`](#eslint-plugin-jsdoc-rules-require-property) - * [`require-property-description`](#eslint-plugin-jsdoc-rules-require-property-description) - * [`require-property-name`](#eslint-plugin-jsdoc-rules-require-property-name) - * [`require-property-type`](#eslint-plugin-jsdoc-rules-require-property-type) - * [`require-returns-check`](#eslint-plugin-jsdoc-rules-require-returns-check) - * [`require-returns-description`](#eslint-plugin-jsdoc-rules-require-returns-description) - * [`require-returns-type`](#eslint-plugin-jsdoc-rules-require-returns-type) - * [`require-returns`](#eslint-plugin-jsdoc-rules-require-returns) - * [`require-throws`](#eslint-plugin-jsdoc-rules-require-throws) - * [`require-yields`](#eslint-plugin-jsdoc-rules-require-yields) - * [`require-yields-check`](#eslint-plugin-jsdoc-rules-require-yields-check) - * [`sort-tags`](#eslint-plugin-jsdoc-rules-sort-tags) - * [`tag-lines`](#eslint-plugin-jsdoc-rules-tag-lines) - * [`valid-types`](#eslint-plugin-jsdoc-rules-valid-types) - - +* [eslint-plugin-jsdoc](#user-content-eslint-plugin-jsdoc) + * [Installation](#user-content-eslint-plugin-jsdoc-installation) + * [Configuration](#user-content-eslint-plugin-jsdoc-configuration) + * [Options](#user-content-eslint-plugin-jsdoc-options) + * [Settings](#user-content-eslint-plugin-jsdoc-settings) + * [Allow tags (`@private` or `@internal`) to disable rules for that comment block](#user-content-eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block) + * [`maxLines` and `minLines`](#user-content-eslint-plugin-jsdoc-settings-maxlines-and-minlines) + * [Mode](#user-content-eslint-plugin-jsdoc-settings-mode) + * [Alias Preference](#user-content-eslint-plugin-jsdoc-settings-alias-preference) + * [`@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`](#user-content-eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields) + * [Settings to Configure `check-types` and `no-undefined-types`](#user-content-eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types) + * [`structuredTags`](#user-content-eslint-plugin-jsdoc-settings-structuredtags) + * [Advanced](#user-content-eslint-plugin-jsdoc-advanced) + * [AST and Selectors](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) + * [Rules](#user-content-eslint-plugin-jsdoc-rules) + * [`check-access`](#user-content-eslint-plugin-jsdoc-rules-check-access) + * [`check-alignment`](#user-content-eslint-plugin-jsdoc-rules-check-alignment) + * [`check-examples`](#user-content-eslint-plugin-jsdoc-rules-check-examples) + * [`check-indentation`](#user-content-eslint-plugin-jsdoc-rules-check-indentation) + * [`check-line-alignment`](#user-content-eslint-plugin-jsdoc-rules-check-line-alignment) + * [`check-param-names`](#user-content-eslint-plugin-jsdoc-rules-check-param-names) + * [`check-property-names`](#user-content-eslint-plugin-jsdoc-rules-check-property-names) + * [`check-syntax`](#user-content-eslint-plugin-jsdoc-rules-check-syntax) + * [`check-tag-names`](#user-content-eslint-plugin-jsdoc-rules-check-tag-names) + * [`check-types`](#user-content-eslint-plugin-jsdoc-rules-check-types) + * [`check-values`](#user-content-eslint-plugin-jsdoc-rules-check-values) + * [`empty-tags`](#user-content-eslint-plugin-jsdoc-rules-empty-tags) + * [`implements-on-classes`](#user-content-eslint-plugin-jsdoc-rules-implements-on-classes) + * [`match-description`](#user-content-eslint-plugin-jsdoc-rules-match-description) + * [`match-name`](#user-content-eslint-plugin-jsdoc-rules-match-name) + * [`multiline-blocks`](#user-content-eslint-plugin-jsdoc-rules-multiline-blocks) + * [`newline-after-description`](#user-content-eslint-plugin-jsdoc-rules-newline-after-description) + * [`no-bad-blocks`](#user-content-eslint-plugin-jsdoc-rules-no-bad-blocks) + * [`no-defaults`](#user-content-eslint-plugin-jsdoc-rules-no-defaults) + * [`no-missing-syntax`](#user-content-eslint-plugin-jsdoc-rules-no-missing-syntax) + * [`no-multi-asterisks`](#user-content-eslint-plugin-jsdoc-rules-no-multi-asterisks) + * [`no-restricted-syntax`](#user-content-eslint-plugin-jsdoc-rules-no-restricted-syntax) + * [`no-types`](#user-content-eslint-plugin-jsdoc-rules-no-types) + * [`no-undefined-types`](#user-content-eslint-plugin-jsdoc-rules-no-undefined-types) + * [`require-asterisk-prefix`](#user-content-eslint-plugin-jsdoc-rules-require-asterisk-prefix) + * [`require-description-complete-sentence`](#user-content-eslint-plugin-jsdoc-rules-require-description-complete-sentence) + * [`require-description`](#user-content-eslint-plugin-jsdoc-rules-require-description) + * [`require-example`](#user-content-eslint-plugin-jsdoc-rules-require-example) + * [`require-file-overview`](#user-content-eslint-plugin-jsdoc-rules-require-file-overview) + * [`require-hyphen-before-param-description`](#user-content-eslint-plugin-jsdoc-rules-require-hyphen-before-param-description) + * [`require-jsdoc`](#user-content-eslint-plugin-jsdoc-rules-require-jsdoc) + * [`require-param-description`](#user-content-eslint-plugin-jsdoc-rules-require-param-description) + * [`require-param-name`](#user-content-eslint-plugin-jsdoc-rules-require-param-name) + * [`require-param-type`](#user-content-eslint-plugin-jsdoc-rules-require-param-type) + * [`require-param`](#user-content-eslint-plugin-jsdoc-rules-require-param) + * [`require-property`](#user-content-eslint-plugin-jsdoc-rules-require-property) + * [`require-property-description`](#user-content-eslint-plugin-jsdoc-rules-require-property-description) + * [`require-property-name`](#user-content-eslint-plugin-jsdoc-rules-require-property-name) + * [`require-property-type`](#user-content-eslint-plugin-jsdoc-rules-require-property-type) + * [`require-returns-check`](#user-content-eslint-plugin-jsdoc-rules-require-returns-check) + * [`require-returns-description`](#user-content-eslint-plugin-jsdoc-rules-require-returns-description) + * [`require-returns-type`](#user-content-eslint-plugin-jsdoc-rules-require-returns-type) + * [`require-returns`](#user-content-eslint-plugin-jsdoc-rules-require-returns) + * [`require-throws`](#user-content-eslint-plugin-jsdoc-rules-require-throws) + * [`require-yields`](#user-content-eslint-plugin-jsdoc-rules-require-yields) + * [`require-yields-check`](#user-content-eslint-plugin-jsdoc-rules-require-yields-check) + * [`sort-tags`](#user-content-eslint-plugin-jsdoc-rules-sort-tags) + * [`tag-lines`](#user-content-eslint-plugin-jsdoc-rules-tag-lines) + * [`valid-types`](#user-content-eslint-plugin-jsdoc-rules-valid-types) + + + ## Installation @@ -92,6 +94,7 @@ globally too. Otherwise, install it locally. npm install --save-dev eslint-plugin-jsdoc ``` + ## Configuration @@ -174,6 +177,7 @@ which enables the rules commented above as "recommended": You can then selectively add to or override the recommended rules. + ## Options @@ -202,9 +206,11 @@ object supplied as the second argument in an array after the error level } ``` + ## Settings + ### Allow tags (@private or @internal) to disable rules for that comment block @@ -217,6 +223,7 @@ object supplied as the second argument in an array after the error level on which a `@internal` tag occurs. Defaults to `false`. Note: This has no effect with the rule `empty-tags` (which checks `@internal` itself). + ### maxLines and minLines @@ -229,6 +236,7 @@ be enforced so as to report problems if a jsdoc block is not found within the specified boundaries. The settings are also used in the fixer to determine how many line breaks to add when a block is missing. + ### Mode @@ -257,6 +265,7 @@ how many line breaks to add when a block is missing. - Disallows namepath on `@interface` for "closure" mode in `valid-types` (and avoids checking in other rules) + ### Alias Preference @@ -349,6 +358,7 @@ See `check-tag-names` for how that fact can be used to set an alias to itself to allow both the alias and the default (since aliases are otherwise not permitted unless used in `tagNamePreference`). + #### Default Preferred Aliases @@ -388,6 +398,7 @@ This setting is utilized by the the rule for tag name checking - `require-returns-description` - `require-returns-type` + ### @override/@augments/@extends/@implements/@ignore Without Accompanying @param/@description/@example/@returns/@throws/@yields @@ -418,6 +429,7 @@ The format of the configuration is as follows: } ``` + ### Settings to Configure check-types and no-undefined-types @@ -483,6 +495,7 @@ key nor the value will be reported. Thus in `check-types`, this fact can be used to allow both `object` and `Object` if one has a `preferredTypes` key `object: 'Object'` and `Object: 'object'`. + ### structuredTags @@ -528,9 +541,11 @@ values are objects with the following optional properties: name (`@throws Some text`); does not require that both exist but disallows just an empty tag. + ## Advanced + ### AST and Selectors @@ -546,6 +561,7 @@ your files' code which are of interest to check. However, in `eslint-plugin-jsdoc`, we also allow you to use these selectors to define additional contexts where you wish our own rules to be applied. + #### contexts format @@ -582,6 +598,7 @@ properties: function). See [@es-joy/jsdoccomment](https://github.com/es-joy/jsdoccomment) for the precise structure of the comment (and comment type) nodes. + #### Discovering available AST definitions @@ -602,6 +619,7 @@ providing some of your JavaScript to the wonderful [AST Explorer](https://astexplorer.net/) tool and see what AST is built out of your code. You can set the tool to the specific parser which you are using. + #### Uses/Tips for AST @@ -623,9 +641,11 @@ to the selector you wish so as to get messages reported in the bottom right pane which match your [esquery](https://github.com/estools/esquery/#readme) selector). + ## Rules + ### check-access @@ -800,6 +820,7 @@ function quux (foo) { ```` + ### check-alignment @@ -943,6 +964,7 @@ function quux (foo) { ```` + ### check-examples @@ -953,11 +975,13 @@ Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also has options to lint the default values of optional `@param`/`@arg`/`@argument` and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags. + #### Options The options below all default to no-op/`false` except as noted. + ##### captionRequired @@ -969,6 +993,7 @@ the beginning of any `@example`. Used only for `@example`. + ##### exampleCodeRegex and rejectExampleCodeRegex @@ -998,6 +1023,7 @@ If neither is in use, all examples will be matched. Note also that even if `captionRequired` is not set, any initial `` will be stripped out before doing the regex matching. + ##### paddedIndent @@ -1019,6 +1045,7 @@ out before evaluation. Only applied to `@example` linting. + ##### reportUnusedDisableDirectives @@ -1031,6 +1058,7 @@ Inline ESLint config within `@example` JavaScript is allowed (or within 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, checkEslintrc, and baseConfig) @@ -1083,6 +1111,7 @@ by decreasing precedence: * `baseConfig` - Set to an object of rules with the same schema as `.eslintrc.*` for defaults. + ##### Rules Disabled by Default Unless noDefaultExampleRules is Set to true @@ -1119,6 +1148,7 @@ expression-oriented rules will be used by default as well: * `no-unused-expressions` - Disabled. * `chai-friendly/no-unused-expressions` - Disabled. + ##### Options for checking other than @example (checkDefaults, checkParams, or checkProperties) @@ -1692,6 +1722,7 @@ const functionName = function (paramOne, paramTwo, ```` + ### check-indentation @@ -1711,11 +1742,13 @@ the following description is not reported: */ ``` + #### Options This rule has an object option. + ##### excludeTags @@ -1965,6 +1998,7 @@ function MyDecorator(options: { myOptions: number }) { ```` + ### check-line-alignment @@ -1972,6 +2006,7 @@ Reports invalid alignment of JSDoc block lines. This is a [standard recommended to WordPress code](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/#aligning-comments), for example. + #### Options @@ -1985,6 +2020,7 @@ space is present after the asterisk delimiter. After the string, an options object is allowed with the following properties. + ##### tags @@ -1992,6 +2028,7 @@ Use this to change the tags which are sought for alignment changes. *Currently* *only works with the "never" option.* Defaults to an array of `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return']`. + ##### customSpacings @@ -2651,11 +2688,13 @@ const fn = ({ids}) => {} ```` + ### check-param-names Ensures that parameter names in JSDoc match those in the function declaration. + #### Destructuring @@ -2682,19 +2721,23 @@ other properties, so in looking at the docs alone without looking at the function signature, the disadvantage of enabling this option is that it may appear that there is an actual property named `extra`. + #### Options + ##### checkRestProperty See the "Destructuring" section. Defaults to `false`. + ##### checkTypesPattern See `require-param` under the option of the same name. + ##### enableFixer @@ -2705,6 +2748,7 @@ Note that this option will remove duplicates of the same name even if the definitions do not match in other ways (e.g., the second param will be removed even if it has a different type or description). + ##### allowExtraTrailingParamDocs @@ -2713,11 +2757,13 @@ representing future expected or virtual params) to be present without needing their presence within the function signature. Other inconsistencies between `@param`'s and present function parameters will still be reported. + ##### checkDestructured Whether to check destructured properties. Defaults to `true`. + ##### useDefaultObjectProperties @@ -2726,6 +2772,7 @@ where instead of destructuring, a whole plain object is supplied as default value but you wish its keys to be considered as signalling that the properties are present and can therefore be documented. Defaults to `false`. + ##### disableExtraPropertyReporting @@ -3598,15 +3645,18 @@ const foo = ([, b]) => b; ```` + ### check-property-names Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots. + #### Options + ##### enableFixer @@ -3812,6 +3862,7 @@ function quux (code = 1) { ```` + ### check-syntax @@ -3873,6 +3924,7 @@ function quux (foo) { ```` + ### check-tag-names @@ -4050,9 +4102,11 @@ typeSummary wizaction ``` + #### Options + ##### definedTags @@ -4065,6 +4119,7 @@ The format is as follows: } ``` + #### jsxTags @@ -4713,6 +4768,7 @@ export function transient(target?: T): T { ```` + ### check-types @@ -4736,6 +4792,7 @@ Date RegExp ``` + #### Options @@ -4785,6 +4842,7 @@ Note that if there is an error [parsing](https://github.com/jsdoc-type-pratt-par types for a tag, the function will silently ignore that tag, leaving it to the `valid-types` rule to report parsing errors. + #### Why not capital case everything? @@ -5802,6 +5860,7 @@ function a () {} ```` + ### check-values @@ -5822,21 +5881,25 @@ This rule checks the values for a handful of tags: 'constant', 'event', 'external', 'file', 'function', 'member', 'mixin', 'module', 'namespace', 'typedef', + #### Options + ##### allowedAuthors An array of allowable author values. If absent, only non-whitespace will be checked for. + ##### allowedLicenses An array of allowable license values or `true` to allow any license text. If present as an array, will be used in place of SPDX identifiers. + ##### licensePattern @@ -5851,6 +5914,7 @@ Note that the `/` delimiters are optional, but necessary to add flags. Defaults to using the `u` flag, so to add your own flags, encapsulate your expression as a string, but like a literal, e.g., `/^mit$/ui`. + ##### numericOnlyVariation @@ -6137,6 +6201,7 @@ function quux (foo) { ```` + ### empty-tags @@ -6171,9 +6236,11 @@ causes rules not to take effect). Similarly, `@internal` will still be checked for content by this rule even with `settings.jsdoc.ignoreInternal` set to `true`. + #### Options + ##### tags @@ -6332,6 +6399,7 @@ function quux () {} ```` + ### implements-on-classes @@ -6344,9 +6412,11 @@ To indicate that a function follows another function's signature, one might instead use `@type` to indicate the `@function` or `@callback` to which the function is adhering. + #### Options + ##### contexts @@ -6359,7 +6429,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -6528,6 +6598,7 @@ function quux () { ```` + ### match-description @@ -6555,9 +6626,11 @@ case-insensitive unless one opts in to add the `i` flag. You can add the `s` flag if you want `.` to match newlines. Note, however, that the trailing newlines of a description will not be matched. + #### Options + ##### matchDescription @@ -6570,6 +6643,7 @@ You can supply your own expression to override the default, passing a } ``` + ##### message @@ -6586,6 +6660,7 @@ You may provide a custom default message by using the following format: This can be overridden per tag or for the main block description by setting `message` within `tags` or `mainDescription`, respectively. + ##### tags @@ -6635,6 +6710,7 @@ its "description" (e.g., for `@returns {someType} some description`, the description is `some description` while for `@some-tag xyz`, the description is `xyz`). + ##### mainDescription @@ -6675,6 +6751,7 @@ You may also provide an object with `message`: } ``` + ##### contexts @@ -6684,7 +6761,7 @@ Set this to an array of strings representing the AST context (or an object with classes). Overrides the default contexts (see below). Set to `"any"` if you want the rule to apply to any jsdoc block throughout your files. -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -7432,6 +7509,7 @@ function quux () { ```` + ### match-name @@ -7444,11 +7522,13 @@ name will actually be part of the description (e.g., for `structuredTags` setting (if `name: false`, this rule will not apply to that tag). + #### Options A single options object with the following properties: + ##### match @@ -7473,7 +7553,7 @@ properties, all of which act to confine one another: - `context` - AST to confine the allowing or disallowing to jsdoc blocks associated with a particular context. See the - ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) + ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. - `comment` - As with `context` but AST for the JSDoc block comment and types @@ -7643,6 +7723,7 @@ class A { ```` + ### multiline-blocks @@ -7655,11 +7736,13 @@ all jsdoc blocks! Also allows for preventing text at the very beginning or very end of blocks. + #### Options A single options object with the following properties. + ##### noZeroLineText (defaults to true) @@ -7668,6 +7751,7 @@ space will be reported. (Text after a newline is not reported.) `noMultilineBlocks` will have priority over this rule if it applies. + ##### noFinalLineText (defaults to true) @@ -7676,12 +7760,14 @@ line will be reported. (Text preceding a newline is not reported.) `noMultilineBlocks` will have priority over this rule if it applies. + ##### noSingleLineBlocks (defaults to false) If this is `true`, any single line blocks will be reported, except those which are whitelisted in `singleLineTags`. + ##### singleLineTags (defaults to ['lends', 'type']) @@ -7691,6 +7777,7 @@ cause all single line blocks to be reported. If `'*'` is present, then the presence of a tag will allow single line blocks (but not if a tag is missing). + ##### noMultilineBlocks (defaults to false) @@ -7698,6 +7785,7 @@ Requires that jsdoc blocks are restricted to single lines only unless impacted by the options `minimumLengthForMultiline`, `multilineTags`, or `allowMultipleTags`. + ##### minimumLengthForMultiline (defaults to not being in effect) @@ -7707,6 +7795,7 @@ be permitted if containing at least the given amount of text. If not set, multiline blocks will not be permitted regardless of length unless a relevant tag is present and `multilineTags` is set. + ##### multilineTags (defaults to ['*']) @@ -7723,6 +7812,7 @@ such a tag will cause multiline blocks to be allowed. You may set this to an empty array to prevent any tag from permitting multiple lines. + ##### allowMultipleTags (defaults to true) @@ -8010,11 +8100,13 @@ The following patterns are not considered problems: ```` + ### newline-after-description Enforces a consistent padding of the block description. + #### Options @@ -8249,6 +8341,7 @@ function example() { ```` + ### no-bad-blocks @@ -8258,11 +8351,13 @@ asterisks, but which appear to be intended as jsdoc blocks due to the presence of whitespace followed by whitespace or asterisks, and an at-sign (`@`) and some non-whitespace (as with a jsdoc block tag). + #### Options Takes an optional options object with the following. + ##### ignore @@ -8272,6 +8367,7 @@ a multi-comment block and at-sign `/* @`. Defaults to `['ts-check', 'ts-expect-error', 'ts-ignore', 'ts-nocheck']` (some directives [used by TypeScript](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check)). + ##### preventAllMultiAsteriskBlocks @@ -8394,6 +8490,7 @@ function quux (foo) { ```` + ### no-defaults @@ -8409,9 +8506,11 @@ tag is attached). Unless your `@default` is on a function, you will need to set `contexts` to an appropriate context, including, if you wish, "any". + #### Options + ##### noOptionalParamNames @@ -8421,6 +8520,7 @@ the presence of ES6 default parameters (bearing in mind that such "defaults" are only applied when the supplied value is missing or `undefined` but not for `null` or other "falsey" values). + ##### contexts @@ -8432,7 +8532,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -8569,6 +8669,7 @@ const a = {}; ```` + ### no-missing-syntax @@ -8606,9 +8707,11 @@ which are not adequate to satisfy a condition, e.g., not report if there were only a function declaration of the name "ignoreMe" (though it would report by function declarations of other names). + #### Options + ##### contexts @@ -8627,7 +8730,7 @@ your files (as is necessary for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -8806,6 +8909,7 @@ function quux () { ```` + ### no-multi-asterisks @@ -8815,9 +8919,11 @@ Note that if you wish to prevent multiple asterisks at the very beginning of the jsdoc block, you should use `no-bad-blocks` (as that is not proper jsdoc and that rule is for catching blocks which only seem like jsdoc). + #### Options + ##### allowWhitespace (defaults to false) @@ -8829,6 +8935,7 @@ Set to `true` if you wish to allow asterisks after a space (as with Markdown): */ ``` + ##### preventAtMiddleLines (defaults to true) @@ -8841,6 +8948,7 @@ Prevent the likes of this: */ ``` + ##### preventAtEnd (defaults to true) @@ -9058,6 +9166,7 @@ function foo() { ```` + ### no-restricted-syntax @@ -9075,9 +9184,11 @@ structures, (whether or not you add a specific `comment` condition). Note that if your parser supports comment AST (as [jsdoc-eslint-parser](https://github.com/brettz9/jsdoc-eslint-parser) is designed to do), you can just use ESLint's rule. + #### Options + ##### contexts @@ -9092,7 +9203,7 @@ your files (as is necessary for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -9270,6 +9381,7 @@ const MY_ENUM = Object.freeze({ ```` + ### no-types @@ -9278,9 +9390,11 @@ This rule reports types being used on `@param` or `@returns`. The rule is intended to prevent the indication of types on tags where the type information would be redundant with TypeScript. + #### Options + ##### contexts @@ -9292,7 +9406,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -9405,6 +9519,7 @@ function quux (foo) { ```` + ### no-undefined-types @@ -9451,6 +9566,7 @@ reporting on use of that namepath elsewhere) and/or that a tag's `type` is `false` (and should not be checked for types). If the `type` is an array, that array's items will be considered as defined for the purposes of that tag. + #### Options @@ -10076,11 +10192,13 @@ export class Foo { ```` + ### require-asterisk-prefix Requires that each JSDoc line starts with an `*`. + #### Options @@ -10092,6 +10210,7 @@ and use the `tags` option to apply to specific tags only. After the string option, one may add an object with the following. + ##### tags @@ -10349,6 +10468,7 @@ function quux (foo) { ```` + ### require-description-complete-sentence @@ -10366,9 +10486,11 @@ Requires that block description, explicit `@description`, and * Periods after items within the `abbreviations` option array are not treated as sentence endings. + #### Options + ##### tags @@ -10393,6 +10515,7 @@ its "description" (e.g., for `@returns {someType} some description`, the description is `some description` while for `@some-tag xyz`, the description is `xyz`). + ##### abbreviations @@ -10400,6 +10523,7 @@ You can provide an `abbreviations` options array to avoid such strings of text being treated as sentence endings when followed by dots. The `.` is not necessary at the end of the array items. + ##### newlineBeforeCapsAssumesBadSentenceEnd @@ -11059,6 +11183,7 @@ export default (foo) => { ```` + ### require-description @@ -11071,6 +11196,7 @@ Requires that all functions have a description. is `"tag"`) must have a non-empty description that explains the purpose of the method. + #### Options @@ -11612,6 +11738,7 @@ class quux { ```` + ### require-example @@ -11621,11 +11748,13 @@ Requires that all functions have examples. * Every example tag must have a non-empty description that explains the method's usage. + #### Options This rule has an object option. + ##### exemptedBy @@ -11635,12 +11764,14 @@ block avoids the need for an `@example`. Defaults to an array with so be sure to add back `inheritdoc` if you wish its presence to cause exemption of the rule. + ##### exemptNoArguments Boolean to indicate that no-argument functions should not be reported for missing `@example` declarations. + ##### contexts @@ -11650,25 +11781,29 @@ Set this to an array of strings representing the AST context (or an object with classes). Overrides the default contexts (see below). Set to `"any"` if you want the rule to apply to any jsdoc block throughout your files. -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. + ##### checkGetters A value indicating whether getters should be checked. Defaults to `false`. + ##### checkSetters A value indicating whether setters should be checked. Defaults to `false`. + #### Fixer @@ -11943,6 +12078,7 @@ function quux () { ```` + ### require-file-overview @@ -11956,9 +12092,11 @@ Checks that: as being when the overview tag is not preceded by anything other than a comment. + #### Options + ##### tags @@ -12237,11 +12375,13 @@ function quux () { ```` + ### require-hyphen-before-param-description Requires (or disallows) a hyphen before the `@param` description. + #### Options @@ -12467,17 +12607,20 @@ function main(argv) { ```` + ### require-jsdoc Checks for presence of jsdoc comments, on class declarations as well as functions. + #### Options Accepts one optional options object with the following optional keys. + ##### publicOnly @@ -12494,6 +12637,7 @@ otherwise noted): - `cjs` - CommonJS exports are checked for JSDoc comments (Defaults to `true`) - `window` - Window global exports are checked for JSDoc comments + ##### require @@ -12507,6 +12651,7 @@ An object with the following optional boolean keys which all default to - `FunctionExpression` - `MethodDefinition` + ##### contexts @@ -12520,9 +12665,10 @@ block which will otherwise be added. Defaults to an empty array. Note that you may need to disable `require` items (e.g., `MethodDefinition`) if you are specifying a more precise form in `contexts` (e.g., `MethodDefinition:not([accessibility="private"] > FunctionExpression`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. + ##### exemptEmptyConstructors @@ -12532,6 +12678,7 @@ When `true`, the rule will not report missing jsdoc blocks above constructors with no parameters or return values (this is enabled by default as the class name or description should be seen as sufficient to convey intent). + ##### exemptEmptyFunctions @@ -12541,6 +12688,7 @@ When `true`, the rule will not report missing jsdoc blocks above functions/methods with no parameters or return values (intended where function/method names are sufficient for themselves as documentation). + ##### checkConstructors @@ -12548,6 +12696,7 @@ A value indicating whether `constructor`s should be checked. Defaults to `true`. When `true`, `exemptEmptyConstructors` may still avoid reporting when no parameters or return values are found. + ##### checkGetters @@ -12557,6 +12706,7 @@ getters should be checked but only when there is no setter. This may be useful if one only wishes documentation on one of the two accessors. Defaults to `false`. + ##### checkSetters @@ -12566,6 +12716,7 @@ setters should be checked but only when there is no getter. This may be useful if one only wishes documentation on one of the two accessors. Defaults to `false`. + ##### enableFixer @@ -14156,14 +14307,17 @@ export class User { ```` + ### require-param-description Requires that each `@param` tag has a `description` value. + #### Options + ##### contexts @@ -14175,7 +14329,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -14276,6 +14430,7 @@ function quux (foo) { ```` + ### require-param-name @@ -14285,9 +14440,11 @@ Requires that all function parameters have names. > > [JSDoc](https://jsdoc.app/tags-param.html#overview) + #### Options + ##### contexts @@ -14299,7 +14456,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -14416,14 +14573,17 @@ function example(cb) { ```` + ### require-param-type Requires that each `@param` tag has a `type` value. + #### Options + ##### contexts @@ -14435,7 +14595,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -14536,11 +14696,13 @@ function quux (foo) { ```` + ### require-param Requires that all function parameters are documented. + #### Fixer @@ -14548,6 +14710,7 @@ Adds `@param ` for each tag present in the function signature but missing in the jsdoc. Can be disabled by setting the `enableFixer` option to `false`. + ##### Destructured object and array naming @@ -14600,6 +14763,7 @@ function quux ([foo, bar]) { */ ``` + ##### Missing root fixing @@ -14635,6 +14799,7 @@ numeric component). And one can have the count begin at another number (e.g., `1`) by changing `autoIncrementBase` from the default of `0`. + ##### Rest Element (RestElement) insertions @@ -14687,6 +14852,7 @@ function baar ([a, ...extra]) { ...because it does not use the `...` syntax in the type. + ##### Object Rest Property insertions @@ -14722,16 +14888,19 @@ other properties, so in looking at the docs alone without looking at the function signature, it may appear that there is an actual property named `extra`. + #### Options An options object accepts the following optional properties: + ##### enableFixer Whether to enable the fixer. Defaults to `true`. + ##### enableRootFixer @@ -14739,12 +14908,14 @@ Whether to enable the auto-adding of incrementing roots (see the "Fixer" section). Defaults to `true`. Has no effect if `enableFixer` is set to `false`. + ##### enableRestElementFixer Whether to enable the rest element fixer (see "Rest Element (`RestElement`) insertions"). Defaults to `true`. + ##### checkRestProperty @@ -14799,12 +14970,14 @@ function quux ({num, ...extra}) { } ``` + ##### autoIncrementBase Numeric to indicate the number at which to begin auto-incrementing roots. Defaults to `0`. + ##### unnamedRootBase @@ -14831,6 +15004,7 @@ function quux ({foo}, [bar], {baz}) { */ ``` + ##### exemptedBy @@ -14840,6 +15014,7 @@ avoids the need for a `@param`. Defaults to an array with so be sure to add back `inheritdoc` if you wish its presence to cause exemption of the rule. + ##### checkTypesPattern @@ -14875,6 +15050,7 @@ You could set this regular expression to a more expansive list, or you could restrict it such that even types matching those strings would not need destructuring. + ##### contexts @@ -14884,30 +15060,35 @@ Overrides the default contexts (see below). May be useful for adding such as `TSMethodSignature` in TypeScript or restricting the contexts which are checked. -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. + ##### checkGetters A value indicating whether getters should be checked. Defaults to `false`. + ##### checkSetters A value indicating whether setters should be checked. Defaults to `false`. + ##### checkDestructured Whether to require destructured properties. Defaults to `true`. + ##### checkDestructuredRoots @@ -14921,6 +15102,7 @@ implied to be `false` (i.e., the inside of the roots will not be checked either, e.g., it will also not complain if `a` or `b` do not have their own documentation). Defaults to `true`. + ##### useDefaultObjectProperties @@ -16264,6 +16446,7 @@ export function testFn1 ({ prop = { a: 1, b: 2 } }) { ```` + ### require-property @@ -16273,6 +16456,7 @@ when their type is a plain `object`, `Object`, or `PlainObject`. Note that any other type, including a subtype of object such as `object`, will not be reported. + #### Fixer @@ -16371,6 +16555,7 @@ function quux () { ```` + ### require-property-description @@ -16440,6 +16625,7 @@ The following patterns are not considered problems: ```` + ### require-property-name @@ -16500,6 +16686,7 @@ The following patterns are not considered problems: ```` + ### require-property-type @@ -16560,6 +16747,7 @@ The following patterns are not considered problems: ```` + ### require-returns-check @@ -16572,6 +16760,7 @@ is set to `false` no non-`undefined` returned or resolved value is found. Will also report if multiple `@returns` tags are present. + #### Options @@ -17149,6 +17338,7 @@ function * quux() {} ```` + ### require-returns-description @@ -17156,9 +17346,11 @@ Requires that the `@returns` tag has a `description` value. The error will not be reported if the return value is `void` or `undefined` or if it is `Promise` or `Promise`. + #### Options + ##### contexts @@ -17170,7 +17362,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -17307,14 +17499,17 @@ function quux () { ```` + ### require-returns-type Requires that `@returns` tag has `type` value. + #### Options + ##### contexts @@ -17326,7 +17521,7 @@ for finding function blocks not attached to a function declaration or expression, i.e., `@callback` or `@function` (or its aliases `@func` or `@method`) (including those associated with an `@interface`). -See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) +See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. ||| @@ -17428,6 +17623,7 @@ function quux () { ```` + ### require-returns @@ -17435,6 +17631,7 @@ Requires that returns are documented. Will also report if multiple `@returns` tags are present. + #### Options @@ -18518,11 +18715,13 @@ export const sleep = (ms: number) => { ```` + ### require-throws Requires that throw statements are documented. + #### Options @@ -18816,6 +19015,7 @@ function quux (foo) { ```` + ### require-yields @@ -18826,6 +19026,7 @@ Will also report if multiple `@yields` tags are present. See the `next`, `forceRequireNext`, and `nextWithGeneratorTag` options for an option to expect a non-standard `@next` tag. + #### Options @@ -19618,6 +19819,7 @@ function * quux (foo) { ```` + ### require-yields-check @@ -19636,6 +19838,7 @@ function bodies. Will also report if multiple `@yields` tags are present. + #### Options @@ -20140,6 +20343,7 @@ function * quux (foo) { ```` + ### sort-tags @@ -20147,9 +20351,11 @@ Sorts tags by a specified sequence according to tag name. (Default order originally inspired by [`@homer0/prettier-plugin-jsdoc`](https://github.com/homer0/packages/tree/main/packages/public/prettier-plugin-jsdoc).) + #### Options + ##### tagSequence @@ -20326,6 +20532,7 @@ a fixed order that doesn't change into the future, supply your own ]; ``` + ##### alphabetizeExtras @@ -20477,11 +20684,13 @@ function quux () {} ```` + ### tag-lines Enforces lines (or no lines) between tags. + #### Options @@ -20493,17 +20702,20 @@ for particular tags). The second option is an object with the following optional properties. + ##### count (defaults to 1) Use with "always" to indicate the number of lines to require be present. + ##### noEndLines (defaults to false) Use with "always" to indicate the normal lines to be added after tags should not be added after the final tag. + ##### tags (default to empty object) @@ -20820,13 +21032,14 @@ The following patterns are not considered problems: ```` + ### valid-types Requires all types to be valid JSDoc, Closure, or TypeScript compiler types without syntax errors. Note that what determines a valid type is handled by our type parsing engine, [jsdoc-type-pratt-parser](https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser), -using [`settings.jsdoc.mode`](#eslint-plugin-jsdoc-settings-mode) to +using [`settings.jsdoc.mode`](#user-content-eslint-plugin-jsdoc-settings-mode) to determine whether to use jsdoc-type-pratt-parser's "permissive" parsing or the stricter "jsdoc", "typescript", "closure" modes. @@ -20900,6 +21113,7 @@ for valid types (based on the tag's `type` value), and either portion checked for presence (based on `false` `name` or `type` values or their `required` value). See the setting for more details. + #### Options diff --git a/package.json b/package.json index 7e63394e0..5251f63a9 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ }, "description": "JSDoc linting rules for ESLint.", "devDependencies": { - "@babel/cli": "^7.17.3", + "@babel/cli": "^7.17.6", "@babel/core": "^7.17.5", "@babel/eslint-parser": "^7.17.0", "@babel/node": "^7.16.8", @@ -25,26 +25,26 @@ "@babel/preset-env": "^7.16.11", "@babel/register": "^7.17.0", "@hkdobrev/run-if-changed": "^0.3.1", - "@typescript-eslint/parser": "^5.12.0", + "@typescript-eslint/parser": "^5.13.0", "babel-plugin-add-module-exports": "^1.0.4", "babel-plugin-istanbul": "^6.1.1", "camelcase": "^6.3.0", "chai": "^4.3.6", "cross-env": "^7.0.3", "decamelize": "^5.0.1", - "eslint": "^8.9.0", + "eslint": "^8.10.0", "eslint-config-canonical": "^33.0.1", - "gitdown": "^3.1.4", + "gitdown": "^3.1.5", "glob": "^7.2.0", "husky": "^7.0.4", "lint-staged": "^12.3.4", "lodash.defaultsdeep": "^4.6.1", - "mocha": "^9.2.0", + "mocha": "^9.2.1", "nyc": "^15.1.0", "open-editor": "^3.0.0", "rimraf": "^3.0.2", "semantic-release": "^19.0.2", - "typescript": "^4.5.5" + "typescript": "^4.6.2" }, "engines": { "node": "^12 || ^14 || ^16 || ^17"