3191 lines
123 KiB
TypeScript
3191 lines
123 KiB
TypeScript
export interface Rules {
|
||
/** Checks that `@access` tags have a valid value. */
|
||
"jsdoc/check-access": [];
|
||
|
||
/** Reports invalid alignment of JSDoc block asterisks. */
|
||
"jsdoc/check-alignment":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set to 0 if you wish to avoid the normal requirement for an inner indentation of
|
||
* one space. Defaults to 1 (one space of normal inner indentation).
|
||
*/
|
||
innerIndent?: number;
|
||
}
|
||
];
|
||
|
||
/** @deprecated - Use `getJsdocProcessorPlugin` processor; ensures that (JavaScript) samples within `@example` tags adhere to ESLint rules. */
|
||
"jsdoc/check-examples":
|
||
| []
|
||
| [
|
||
{
|
||
allowInlineConfig?: boolean;
|
||
baseConfig?: {
|
||
[k: string]: unknown;
|
||
};
|
||
captionRequired?: boolean;
|
||
checkDefaults?: boolean;
|
||
checkEslintrc?: boolean;
|
||
checkParams?: boolean;
|
||
checkProperties?: boolean;
|
||
configFile?: string;
|
||
exampleCodeRegex?: string;
|
||
matchingFileName?: string;
|
||
matchingFileNameDefaults?: string;
|
||
matchingFileNameParams?: string;
|
||
matchingFileNameProperties?: string;
|
||
noDefaultExampleRules?: boolean;
|
||
paddedIndent?: number;
|
||
rejectExampleCodeRegex?: string;
|
||
reportUnusedDisableDirectives?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Reports invalid padding inside JSDoc blocks. */
|
||
"jsdoc/check-indentation":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Allows indentation of nested sections on subsequent lines (like bullet lists)
|
||
*/
|
||
allowIndentedSections?: boolean;
|
||
/**
|
||
* Array of tags (e.g., `['example', 'description']`) whose content will be
|
||
* "hidden" from the `check-indentation` rule. Defaults to `['example']`.
|
||
*
|
||
* By default, the whole JSDoc block will be checked for invalid padding.
|
||
* That would include `@example` blocks too, which can get in the way
|
||
* of adding full, readable examples of code without ending up with multiple
|
||
* linting issues.
|
||
*
|
||
* When disabled (by passing `excludeTags: []` option), the following code *will*
|
||
* report a padding issue:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @example
|
||
* * anArray.filter((a) => {
|
||
* * return a.b;
|
||
* * });
|
||
* * /
|
||
* ```
|
||
*/
|
||
excludeTags?: string[];
|
||
}
|
||
];
|
||
|
||
/** Reports invalid alignment of JSDoc block lines. */
|
||
"jsdoc/check-line-alignment":
|
||
| []
|
||
| ["always" | "never" | "any"]
|
||
| [
|
||
"always" | "never" | "any",
|
||
{
|
||
/**
|
||
* An object with any of the following spacing keys set to an integer.
|
||
* If a spacing is not defined, it defaults to one.
|
||
*/
|
||
customSpacings?: {
|
||
/**
|
||
* Affects spacing after the asterisk (e.g., `* @param`)
|
||
*/
|
||
postDelimiter?: number;
|
||
/**
|
||
* Affects spacing after any hyphens in the description (e.g., `* @param {someType} name - A description`)
|
||
*/
|
||
postHyphen?: number;
|
||
/**
|
||
* Affects spacing after the name (e.g., `* @param {someType} name `)
|
||
*/
|
||
postName?: number;
|
||
/**
|
||
* Affects spacing after the tag (e.g., `* @param `)
|
||
*/
|
||
postTag?: number;
|
||
/**
|
||
* Affects spacing after the type (e.g., `* @param {someType} `)
|
||
*/
|
||
postType?: number;
|
||
};
|
||
/**
|
||
* Disables `wrapIndent`; existing wrap indentation is preserved without changes.
|
||
*/
|
||
disableWrapIndent?: boolean;
|
||
/**
|
||
* A boolean to determine whether to preserve the post-delimiter spacing of the
|
||
* main description. If `false` or unset, will be set to a single space.
|
||
*/
|
||
preserveMainDescriptionPostDelimiter?: boolean;
|
||
/**
|
||
* Use this to change the tags which are sought for alignment changes. Defaults to an array of
|
||
* `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template']`.
|
||
*/
|
||
tags?: string[];
|
||
/**
|
||
* The indent that will be applied for tag text after the first line.
|
||
* Default to the empty string (no indent).
|
||
*/
|
||
wrapIndent?: string;
|
||
}
|
||
];
|
||
|
||
/** Checks for dupe `@param` names, that nested param names have roots, and that parameter names in function declarations match JSDoc param names. */
|
||
"jsdoc/check-param-names":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* If set to `true`, this option will allow extra `@param` definitions (e.g.,
|
||
* 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.
|
||
*/
|
||
allowExtraTrailingParamDocs?: boolean;
|
||
/**
|
||
* Whether to check destructured properties. Defaults to `true`.
|
||
*/
|
||
checkDestructured?: boolean;
|
||
/**
|
||
* If set to `true`, will require that rest properties are documented and
|
||
* that any extraneous properties (which may have been within the rest property)
|
||
* are documented. Defaults to `false`.
|
||
*/
|
||
checkRestProperty?: boolean;
|
||
/**
|
||
* Defines a regular expression pattern to indicate which types should be
|
||
* checked for destructured content (and that those not matched should not
|
||
* be checked).
|
||
*
|
||
* When one specifies a type, unless it is of a generic type, like `object`
|
||
* or `array`, it may be considered unnecessary to have that object's
|
||
* destructured components required, especially where generated docs will
|
||
* link back to the specified type. For example:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param {SVGRect} bbox - a SVGRect
|
||
* * /
|
||
* export const bboxToObj = function ({x, y, width, height}) {
|
||
* return {x, y, width, height};
|
||
* };
|
||
* ```
|
||
*
|
||
* By default `checkTypesPattern` is set to
|
||
* `/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/v`,
|
||
* meaning that destructuring will be required only if the type of the `@param`
|
||
* (the text between curly brackets) is a match for "Object" or "Array" (with or
|
||
* without initial caps), "PlainObject", or "GenericObject", "GenericArray" (or
|
||
* if no type is present). So in the above example, the lack of a match will
|
||
* mean that no complaint will be given about the undocumented destructured
|
||
* parameters.
|
||
*
|
||
* Note that the `/` delimiters are optional, but necessary to add flags.
|
||
*
|
||
* Defaults to using (only) the `v` flag, so to add your own flags, encapsulate
|
||
* your expression as a string, but like a literal, e.g., `/^object$/vi`.
|
||
*
|
||
* 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.
|
||
*/
|
||
checkTypesPattern?: string;
|
||
/**
|
||
* Whether to check for extra destructured properties. Defaults to `false`. Change
|
||
* to `true` if you want to be able to document properties which are not actually
|
||
* destructured. Keep as `false` if you expect properties to be documented in
|
||
* their own types. Note that extra properties will always be reported if another
|
||
* item at the same level is destructured as destructuring will prevent other
|
||
* access and this option is only intended to permit documenting extra properties
|
||
* that are available and actually used in the function.
|
||
*/
|
||
disableExtraPropertyReporting?: boolean;
|
||
/**
|
||
* Whether to avoid checks for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.
|
||
*/
|
||
disableMissingParamChecks?: boolean;
|
||
/**
|
||
* Set to `true` to auto-remove `@param` duplicates (based on identical
|
||
* names).
|
||
*
|
||
* 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).
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* Set to `true` if you wish to avoid reporting of child property documentation
|
||
* 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`.
|
||
*/
|
||
useDefaultObjectProperties?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots. */
|
||
"jsdoc/check-property-names":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set to `true` to auto-remove `@property` duplicates (based on
|
||
* identical names).
|
||
*
|
||
* 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 property will
|
||
* be removed even if it has a different type or description).
|
||
*/
|
||
enableFixer?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode). */
|
||
"jsdoc/check-syntax": [];
|
||
|
||
/** Reports invalid block tag names. */
|
||
"jsdoc/check-tag-names":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Use an array of `definedTags` strings to configure additional, allowed tags.
|
||
* The format is as follows:
|
||
*
|
||
* ```json
|
||
* {
|
||
* "definedTags": ["note", "record"]
|
||
* }
|
||
* ```
|
||
*/
|
||
definedTags?: string[];
|
||
/**
|
||
* Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* List of tags to allow inline.
|
||
*
|
||
* Defaults to array of `'link', 'linkcode', 'linkplain', 'tutorial'`
|
||
*/
|
||
inlineTags?: string[];
|
||
/**
|
||
* If this is set to `true`, all of the following tags used to control JSX output are allowed:
|
||
*
|
||
* ```
|
||
* jsx
|
||
* jsxFrag
|
||
* jsxImportSource
|
||
* jsxRuntime
|
||
* ```
|
||
*
|
||
* For more information, see the [babel documentation](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx).
|
||
*/
|
||
jsxTags?: boolean;
|
||
/**
|
||
* If this is set to `true`, additionally checks for tag names that are redundant when using a type checker such as TypeScript.
|
||
*
|
||
* These tags are always unnecessary when using TypeScript or similar:
|
||
*
|
||
* ```
|
||
* augments
|
||
* callback
|
||
* class
|
||
* enum
|
||
* implements
|
||
* private
|
||
* property
|
||
* protected
|
||
* public
|
||
* readonly
|
||
* this
|
||
* type
|
||
* typedef
|
||
* ```
|
||
*
|
||
* These tags are unnecessary except when inside a TypeScript `declare` context:
|
||
*
|
||
* ```
|
||
* abstract
|
||
* access
|
||
* class
|
||
* constant
|
||
* constructs
|
||
* default
|
||
* enum
|
||
* export
|
||
* exports
|
||
* function
|
||
* global
|
||
* inherits
|
||
* instance
|
||
* interface
|
||
* member
|
||
* memberof
|
||
* memberOf
|
||
* method
|
||
* mixes
|
||
* mixin
|
||
* module
|
||
* name
|
||
* namespace
|
||
* override
|
||
* property
|
||
* requires
|
||
* static
|
||
* this
|
||
* ```
|
||
*/
|
||
typed?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Checks that any `@template` names are actually used in the connected `@typedef` or type alias. */
|
||
"jsdoc/check-template-names": [];
|
||
|
||
/** Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements). */
|
||
"jsdoc/check-types":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Avoids reporting when a bad type is found on a specified tag.
|
||
*/
|
||
exemptTagContexts?: {
|
||
/**
|
||
* Set a key `tag` to the tag to exempt
|
||
*/
|
||
tag?: string;
|
||
/**
|
||
* Set to `true` to indicate that any types on that tag will be allowed,
|
||
* or to an array of strings which will only allow specific bad types.
|
||
* If an array of strings is given, these must match the type exactly,
|
||
* e.g., if you only allow `"object"`, it will not allow
|
||
* `"object<string, string>"`. Note that this is different from the
|
||
* behavior of `settings.jsdoc.preferredTypes`. This option is useful
|
||
* for normally restricting generic types like `object` with
|
||
* `preferredTypes`, but allowing `typedef` to indicate that its base
|
||
* type is `object`.
|
||
*/
|
||
types?: boolean | string[];
|
||
}[];
|
||
/**
|
||
* Insists that only the supplied option type
|
||
* map is to be used, and that the default preferences (such as "string"
|
||
* over "String") will not be enforced. The option's default is `false`.
|
||
*/
|
||
noDefaults?: boolean;
|
||
/**
|
||
* @deprecated Use the `preferredTypes[preferredType]` setting of the same name instead.
|
||
* If this option is `true`, will currently override `unifyParentAndChildTypeChecks` on the `preferredTypes` setting.
|
||
*/
|
||
unifyParentAndChildTypeChecks?: boolean;
|
||
}
|
||
];
|
||
|
||
/** This rule checks the values for a handful of tags: `@version`, `@since`, `@license` and `@author`. */
|
||
"jsdoc/check-values":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* An array of allowable author values. If absent, only non-whitespace will
|
||
* be checked for.
|
||
*/
|
||
allowedAuthors?: string[];
|
||
/**
|
||
* 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](https://spdx.org/licenses/).
|
||
*/
|
||
allowedLicenses?: string[] | boolean;
|
||
/**
|
||
* A string to be converted into a `RegExp` (with `v` flag) and whose first
|
||
* parenthetical grouping, if present, will match the portion of the license
|
||
* description to check (if no grouping is present, then the whole portion
|
||
* matched will be used). Defaults to `/([^\n\r]*)/gv`, i.e., the SPDX expression
|
||
* is expected before any line breaks.
|
||
*
|
||
* Note that the `/` delimiters are optional, but necessary to add flags.
|
||
*
|
||
* Defaults to using the `v` flag, so to add your own flags, encapsulate
|
||
* your expression as a string, but like a literal, e.g., `/^mit$/vi`.
|
||
*/
|
||
licensePattern?: string;
|
||
/**
|
||
* Whether to enable validation that `@variation` must be a number. Defaults to
|
||
* `false`.
|
||
*/
|
||
numericOnlyVariation?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Converts non-JSDoc comments preceding or following nodes into JSDoc ones */
|
||
"jsdoc/convert-to-jsdoc-comments":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* An array of prefixes to allow at the beginning of a comment.
|
||
*
|
||
* Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
|
||
*
|
||
* Supplying your own value overrides the defaults.
|
||
*/
|
||
allowedPrefixes?: string[];
|
||
/**
|
||
* The contexts array which will be checked for preceding content.
|
||
*
|
||
* Can either be strings or an object with a `context` string and an optional, default `false` `inlineCommentBlock` boolean.
|
||
*
|
||
* Defaults to `ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`, `TSDeclareFunction`.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
context?: string;
|
||
inlineCommentBlock?: boolean;
|
||
}
|
||
)[];
|
||
/**
|
||
* The contexts array which will be checked for content on the same line after.
|
||
*
|
||
* Can either be strings or an object with a `context` string and an optional, default `false` `inlineCommentBlock` boolean.
|
||
*
|
||
* Defaults to an empty array.
|
||
*/
|
||
contextsAfter?: (
|
||
| string
|
||
| {
|
||
context?: string;
|
||
inlineCommentBlock?: boolean;
|
||
}
|
||
)[];
|
||
/**
|
||
* The contexts array which will be checked for content before and on the same
|
||
* line after.
|
||
*
|
||
* Can either be strings or an object with a `context` string and an optional, default `false` `inlineCommentBlock` boolean.
|
||
*
|
||
* Defaults to `VariableDeclarator`, `TSPropertySignature`, `PropertyDefinition`.
|
||
*/
|
||
contextsBeforeAndAfter?: (
|
||
| string
|
||
| {
|
||
context?: string;
|
||
inlineCommentBlock?: boolean;
|
||
}
|
||
)[];
|
||
/**
|
||
* Set to `false` to disable fixing.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* What policy to enforce on the conversion of non-JSDoc comments without
|
||
* line breaks. (Non-JSDoc (mulitline) comments with line breaks will always
|
||
* be converted to `multi` style JSDoc comments.)
|
||
*
|
||
* - `multi` - Convert to multi-line style
|
||
* ```js
|
||
* /**
|
||
* * Some text
|
||
* * /
|
||
* ```
|
||
* - `single` - Convert to single-line style
|
||
* ```js
|
||
* /** Some text * /
|
||
* ```
|
||
*
|
||
* Defaults to `multi`.
|
||
*/
|
||
enforceJsdocLineStyle?: "multi" | "single";
|
||
/**
|
||
* What style of comments to which to apply JSDoc conversion.
|
||
*
|
||
* - `block` - Applies to block-style comments (`/* ... * /`)
|
||
* - `line` - Applies to line-style comments (`// ...`)
|
||
* - `both` - Applies to both block and line-style comments
|
||
*
|
||
* Defaults to `both`.
|
||
*/
|
||
lineOrBlockStyle?: "block" | "line" | "both";
|
||
}
|
||
];
|
||
|
||
/** Checks tags that are expected to be empty (e.g., `@abstract` or `@async`), reporting if they have content */
|
||
"jsdoc/empty-tags":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* If you want additional tags to be checked for their descriptions, you may
|
||
* add them within this option.
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/empty-tags': ['error', {tags: ['event']}]
|
||
* }
|
||
* ```
|
||
*/
|
||
tags?: string[];
|
||
}
|
||
];
|
||
|
||
/** Reports use of JSDoc tags in non-tag positions (in the default "typescript" mode). */
|
||
"jsdoc/escape-inline-tags":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* A listing of tags you wish to allow unescaped. Defaults to an empty array.
|
||
*/
|
||
allowedInlineTags?: string[];
|
||
/**
|
||
* Whether to enable the fixer. Defaults to `false`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* How to escape the inline tag.
|
||
*
|
||
* May be "backticks" to enclose tags in backticks (treating as code segments), or
|
||
* "backslash" to escape tags with a backslash, i.e., `\@`
|
||
*
|
||
* Defaults to "backslash".
|
||
*/
|
||
fixType?: "backticks" | "backslash";
|
||
}
|
||
];
|
||
|
||
/** Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors). */
|
||
"jsdoc/implements-on-classes":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** Reports if JSDoc `import()` statements point to a package which is not listed in `dependencies` or `devDependencies` */
|
||
"jsdoc/imports-as-dependencies": [];
|
||
|
||
/** This rule reports doc comments that only restate their attached name. */
|
||
"jsdoc/informative-docs":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* The `aliases` option allows indicating words as synonyms (aliases) of each other.
|
||
*
|
||
* For example, with `{ aliases: { emoji: ["smiley", "winkey"] } }`, the following comment would be considered uninformative:
|
||
*
|
||
* ```js
|
||
* /** A smiley/winkey. * /
|
||
* let emoji;
|
||
* ```
|
||
*
|
||
* The default `aliases` option is:
|
||
*
|
||
* ```json
|
||
* {
|
||
* "a": ["an", "our"]
|
||
* }
|
||
* ```
|
||
*/
|
||
aliases?: {
|
||
/**
|
||
* This interface was referenced by `undefined`'s JSON-Schema definition
|
||
* via the `patternProperty` ".*".
|
||
*/
|
||
[k: string]: string[];
|
||
};
|
||
/**
|
||
* Tags that should not be checked for valid contents.
|
||
*
|
||
* For example, with `{ excludedTags: ["category"] }`, the following comment would not be considered uninformative:
|
||
*
|
||
* ```js
|
||
* /** @category Types * /
|
||
* function computeTypes(node) {
|
||
* // ...
|
||
* }
|
||
* ```
|
||
*
|
||
* No tags are excluded by default.
|
||
*/
|
||
excludedTags?: string[];
|
||
/**
|
||
* Words that are ignored when searching for one that adds meaning.
|
||
*
|
||
* For example, with `{ uselessWords: ["our"] }`, the following comment would be considered uninformative:
|
||
*
|
||
* ```js
|
||
* /** Our text. * /
|
||
* let text;
|
||
* ```
|
||
*
|
||
* The default `uselessWords` option is:
|
||
*
|
||
* ```json
|
||
* ["a", "an", "i", "in", "of", "s", "the"]
|
||
* ```
|
||
*/
|
||
uselessWords?: string[];
|
||
}
|
||
];
|
||
|
||
/** Enforces minimum number of newlines before JSDoc comment blocks */
|
||
"jsdoc/lines-before-block":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Whether to additionally check the start of blocks, such as classes or functions.
|
||
* Defaults to `false`.
|
||
*/
|
||
checkBlockStarts?: boolean;
|
||
/**
|
||
* An array of tags whose presence in the JSDoc block will prevent the
|
||
* application of the rule. Defaults to `['type']` (i.e., if `@type` is present,
|
||
* lines before the block will not be added).
|
||
*/
|
||
excludedTags?: string[];
|
||
/**
|
||
* This option excludes cases where the JSDoc block occurs on the same line as a
|
||
* preceding code or comment. Defaults to `true`.
|
||
*/
|
||
ignoreSameLine?: boolean;
|
||
/**
|
||
* This option excludes cases where the JSDoc block is only one line long.
|
||
* Defaults to `true`.
|
||
*/
|
||
ignoreSingleLines?: boolean;
|
||
/**
|
||
* The minimum number of lines to require. Defaults to 1.
|
||
*/
|
||
lines?: number;
|
||
}
|
||
];
|
||
|
||
/** Enforces a regular expression pattern on descriptions. */
|
||
"jsdoc/match-description":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied (e.g.,
|
||
* `ClassDeclaration` for ES6 classes).
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want the rule to apply to any
|
||
* JSDoc block throughout your files.
|
||
*
|
||
* See the ["AST and Selectors"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* If you wish to override the main block description without changing the
|
||
* default `match-description` (which can cascade to the `tags` with `true`),
|
||
* you may use `mainDescription`:
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/match-description': ['error', {
|
||
* mainDescription: '[A-Z].*\\.',
|
||
* tags: {
|
||
* param: true,
|
||
* returns: true
|
||
* }
|
||
* }]
|
||
* }
|
||
* ```
|
||
*
|
||
* There is no need to add `mainDescription: true`, as by default, the main
|
||
* block description (and only the main block description) is linted, though you
|
||
* may disable checking it by setting it to `false`.
|
||
*
|
||
* You may also provide an object with `message`:
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/match-description': ['error', {
|
||
* mainDescription: {
|
||
* message: 'Capitalize first word of JSDoc block descriptions',
|
||
* match: '[A-Z].*\\.'
|
||
* },
|
||
* tags: {
|
||
* param: true,
|
||
* returns: true
|
||
* }
|
||
* }]
|
||
* }
|
||
* ```
|
||
*/
|
||
mainDescription?:
|
||
| string
|
||
| boolean
|
||
| {
|
||
match?: string | boolean;
|
||
message?: string;
|
||
};
|
||
/**
|
||
* You can supply your own expression to override the default, passing a
|
||
* `matchDescription` string on the options object.
|
||
*
|
||
* Defaults to using (only) the `v` flag, so
|
||
* to add your own flags, encapsulate your expression as a string, but like a
|
||
* literal, e.g., `/[A-Z].*\./vi`.
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/match-description': ['error', {matchDescription: '[A-Z].*\\.'}]
|
||
* }
|
||
* ```
|
||
*/
|
||
matchDescription?: string;
|
||
/**
|
||
* You may provide a custom default message by using the following format:
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/match-description': ['error', {
|
||
* message: 'The default description should begin with a capital letter.'
|
||
* }]
|
||
* }
|
||
* ```
|
||
*
|
||
* This can be overridden per tag or for the main block description by setting
|
||
* `message` within `tags` or `mainDescription`, respectively.
|
||
*/
|
||
message?: string;
|
||
/**
|
||
* If not set to `false`, will enforce that the following tags have at least
|
||
* some content:
|
||
*
|
||
* - `@copyright`
|
||
* - `@example`
|
||
* - `@see`
|
||
* - `@todo`
|
||
*
|
||
* If you supply your own tag description for any of the above tags in `tags`,
|
||
* your description will take precedence.
|
||
*/
|
||
nonemptyTags?: boolean;
|
||
/**
|
||
* If you want different regular expressions to apply to tags, you may use
|
||
* the `tags` option object:
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/match-description': ['error', {tags: {
|
||
* param: '\\- [A-Z].*\\.',
|
||
* returns: '[A-Z].*\\.'
|
||
* }}]
|
||
* }
|
||
* ```
|
||
*
|
||
* In place of a string, you can also add `true` to indicate that a particular
|
||
* tag should be linted with the `matchDescription` value (or the default).
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/match-description': ['error', {tags: {
|
||
* param: true,
|
||
* returns: true
|
||
* }}]
|
||
* }
|
||
* ```
|
||
*
|
||
* Alternatively, you may supply an object with a `message` property to indicate
|
||
* the error message for that tag.
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/match-description': ['error', {tags: {
|
||
* param: {message: 'Begin with a hyphen', match: '\\- [A-Z].*\\.'},
|
||
* returns: {message: 'Capitalize for returns (the default)', match: true}
|
||
* }}]
|
||
* }
|
||
* ```
|
||
*
|
||
* The tags `@param`/`@arg`/`@argument` and `@property`/`@prop` will be properly
|
||
* parsed to ensure that the matched "description" text includes only the text
|
||
* after the name.
|
||
*
|
||
* All other tags will treat the text following the tag name, a space, and
|
||
* an optional curly-bracketed type expression (and another space) as part of
|
||
* its "description" (e.g., for `@returns {someType} some description`, the
|
||
* description is `some description` while for `@some-tag xyz`, the description
|
||
* is `xyz`).
|
||
*/
|
||
tags?: {
|
||
/**
|
||
* This interface was referenced by `undefined`'s JSON-Schema definition
|
||
* via the `patternProperty` ".*".
|
||
*/
|
||
[k: string]:
|
||
| string
|
||
| true
|
||
| {
|
||
match?: string | true;
|
||
message?: string;
|
||
};
|
||
};
|
||
}
|
||
];
|
||
|
||
/** Reports the name portion of a JSDoc tag if matching or not matching a given regular expression. */
|
||
"jsdoc/match-name":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* `match` is a required option containing an array of objects which determine
|
||
* the conditions whereby a name is reported as being problematic.
|
||
*
|
||
* These objects can have any combination of the following groups of optional
|
||
* properties, all of which act to confine one another.
|
||
*
|
||
* Note that `comment`, even if targeting a specific tag, is used to match the
|
||
* whole block. So if a `comment` finds its specific tag, it may still apply
|
||
* fixes found by the likes of `disallowName` even when a different tag has the
|
||
* disallowed name. An alternative is to ensure that `comment` finds the specific
|
||
* tag of the desired tag and/or name and no `disallowName` (or `allowName`) is
|
||
* supplied. In such a case, only one error will be reported, but no fixer will
|
||
* be applied, however.
|
||
*/
|
||
match: {
|
||
/**
|
||
* Indicates which names are allowed for the given tag (or `*`).
|
||
* Accepts a string regular expression (optionally wrapped between two
|
||
* `/` delimiters followed by optional flags) used to match the name.
|
||
*/
|
||
allowName?: string;
|
||
/**
|
||
* As with `context` but AST for the JSDoc block comment and types.
|
||
*/
|
||
comment?: string;
|
||
/**
|
||
* AST to confine the allowing or disallowing to JSDoc blocks
|
||
* associated with a particular context. See the
|
||
* ["AST and Selectors"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
context?: string;
|
||
/**
|
||
* As with `allowName` but indicates names that are not allowed.
|
||
*/
|
||
disallowName?: string;
|
||
/**
|
||
* An optional custom message to use when there is a match.
|
||
*/
|
||
message?: string;
|
||
/**
|
||
* If `disallowName` is supplied and this value is present, it
|
||
* will replace the matched `disallowName` text.
|
||
*/
|
||
replacement?: string;
|
||
/**
|
||
* This array should include tag names or `*` to indicate the
|
||
* match will apply for all tags (except as confined by any context
|
||
* properties). If `*` is not used, then these rules will only apply to
|
||
* the specified tags. If `tags` is omitted, then `*` is assumed.
|
||
*/
|
||
tags?: string[];
|
||
}[];
|
||
}
|
||
];
|
||
|
||
/** Controls how and whether JSDoc blocks can be expressed as single or multiple line blocks. */
|
||
"jsdoc/multiline-blocks":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* If `noMultilineBlocks` is set to `true` with this option and multiple tags are
|
||
* found in a block, an error will not be reported.
|
||
*
|
||
* Since multiple-tagged lines cannot be collapsed into a single line, this option
|
||
* prevents them from being reported. Set to `false` if you really want to report
|
||
* any blocks.
|
||
*
|
||
* This option will also be applied when there is a block description and a single
|
||
* tag (since a description cannot precede a tag on a single line, and also
|
||
* cannot be reliably added after the tag either).
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
allowMultipleTags?: boolean;
|
||
/**
|
||
* If `noMultilineBlocks` is set with this numeric option, multiline blocks will
|
||
* 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.
|
||
*
|
||
* Defaults to not being in effect.
|
||
*/
|
||
minimumLengthForMultiline?: number;
|
||
/**
|
||
* If `noMultilineBlocks` is set with this option, multiline blocks may be allowed
|
||
* regardless of length as long as a tag or a tag of a certain type is present.
|
||
*
|
||
* If `*` is included in the array, the presence of a tags will allow for
|
||
* multiline blocks (but not when without any tags unless the amount of text is
|
||
* over an amount specified by `minimumLengthForMultiline`).
|
||
*
|
||
* If the array does not include `*` but lists certain tags, the presence of
|
||
* 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.
|
||
*
|
||
* Defaults to `['*']`.
|
||
*/
|
||
multilineTags?: "*" | string[];
|
||
/**
|
||
* For multiline blocks, any non-whitespace text preceding the `* /` on the final
|
||
* line will be reported. (Text preceding a newline is not reported.)
|
||
*
|
||
* `noMultilineBlocks` will have priority over this rule if it applies.
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
noFinalLineText?: boolean;
|
||
/**
|
||
* Requires that JSDoc blocks are restricted to single lines only unless impacted
|
||
* by the options `minimumLengthForMultiline`, `multilineTags`, or
|
||
* `allowMultipleTags`.
|
||
*
|
||
* Defaults to `false`.
|
||
*/
|
||
noMultilineBlocks?: boolean;
|
||
/**
|
||
* If this is `true`, any single line blocks will be reported, except those which
|
||
* are whitelisted in `singleLineTags`.
|
||
*
|
||
* Defaults to `false`.
|
||
*/
|
||
noSingleLineBlocks?: boolean;
|
||
/**
|
||
* For multiline blocks, any non-whitespace text immediately after the `/**` and
|
||
* space will be reported. (Text after a newline is not reported.)
|
||
*
|
||
* `noMultilineBlocks` will have priority over this rule if it applies.
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
noZeroLineText?: boolean;
|
||
/**
|
||
* If this number is set, it indicates a minimum line width for a single line of
|
||
* JSDoc content spread over a multi-line comment block. If a single line is under
|
||
* the minimum length, it will be reported so as to enforce single line JSDoc blocks
|
||
* for such cases. Blocks are not reported which have multi-line descriptions,
|
||
* multiple tags, a block description and tag, or tags with multi-line types or
|
||
* descriptions.
|
||
*
|
||
* Defaults to `null`.
|
||
*/
|
||
requireSingleLineUnderCount?: number;
|
||
/**
|
||
* An array of tags which can nevertheless be allowed as single line blocks when
|
||
* `noSingleLineBlocks` is set. You may set this to a empty array to
|
||
* 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).
|
||
*
|
||
* Defaults to `['lends', 'type']`.
|
||
*/
|
||
singleLineTags?: string[];
|
||
}
|
||
];
|
||
|
||
/** This rule checks for multi-line-style comments which fail to meet the criteria of a JSDoc block. */
|
||
"jsdoc/no-bad-blocks":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* An array of directives that will not be reported if present at the beginning of
|
||
* 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)).
|
||
*/
|
||
ignore?: string[];
|
||
/**
|
||
* A boolean (defaulting to `false`) which if `true` will prevent all
|
||
* JSDoc-like blocks with more than two initial asterisks even those without
|
||
* apparent tag content.
|
||
*/
|
||
preventAllMultiAsteriskBlocks?: boolean;
|
||
}
|
||
];
|
||
|
||
/** If tags are present, this rule will prevent empty lines in the block description. If no tags are present, this rule will prevent extra empty lines in the block description. */
|
||
"jsdoc/no-blank-block-descriptions": [];
|
||
|
||
/** Removes empty blocks with nothing but possibly line breaks */
|
||
"jsdoc/no-blank-blocks":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Whether or not to auto-remove the blank block. Defaults to `false`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
}
|
||
];
|
||
|
||
/** This rule reports defaults being used on the relevant portion of `@param` or `@default`. */
|
||
"jsdoc/no-defaults":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* Set this to `true` to report the presence of optional parameters. May be
|
||
* used if the project is insisting on optionality being indicated by
|
||
* 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).
|
||
*/
|
||
noOptionalParamNames?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Reports when certain comment structures are always expected. */
|
||
"jsdoc/no-missing-syntax":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Use the `minimum` property (defaults to 1) to indicate how many are required
|
||
* for the rule to be reported.
|
||
*
|
||
* Use the `message` property to indicate the specific error to be shown when an
|
||
* error is reported for that context being found missing. You may use
|
||
* `{{context}}` and `{{comment}}` with such messages. Defaults to
|
||
* `"Syntax is required: {{context}}"`, or with a comment, to
|
||
* `"Syntax is required: {{context}} with {{comment}}"`.
|
||
*
|
||
* Set to `"any"` if you want the rule to apply to any JSDoc block throughout
|
||
* 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
message?: string;
|
||
minimum?: number;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** Prevents use of multiple asterisks at the beginning of lines. */
|
||
"jsdoc/no-multi-asterisks":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set to `true` if you wish to allow asterisks after a space (as with Markdown):
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * *bold* text
|
||
* * /
|
||
* ```
|
||
*
|
||
* Defaults to `false`.
|
||
*/
|
||
allowWhitespace?: boolean;
|
||
/**
|
||
* Prevent the likes of this:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* *
|
||
* *
|
||
* ** /
|
||
* ```
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
preventAtEnd?: boolean;
|
||
/**
|
||
* Prevent the likes of this:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* *
|
||
* **
|
||
* * /
|
||
* ```
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
preventAtMiddleLines?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Reports when certain comment structures are present. */
|
||
"jsdoc/no-restricted-syntax":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Use the `message` property to indicate the specific error to be shown when an
|
||
* error is reported for that context being found. Defaults to
|
||
* `"Syntax is restricted: {{context}}"`, or with a comment, to
|
||
* `"Syntax is restricted: {{context}} with {{comment}}"`.
|
||
*
|
||
* Set to `"any"` if you want the rule to apply to any JSDoc block throughout
|
||
* 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
message?: string;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** This rule reports types being used on `@param` or `@returns` (redundant with TypeScript). */
|
||
"jsdoc/no-types":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`, `TSDeclareFunction`, `TSMethodSignature`,
|
||
* `ClassDeclaration`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** Besides some expected built-in types, prohibits any types not specified as globals or within `@typedef`. */
|
||
"jsdoc/no-undefined-types":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Whether to check typedefs for use within the file
|
||
*/
|
||
checkUsedTypedefs?: boolean;
|
||
/**
|
||
* This array can be populated to indicate other types which
|
||
* are automatically considered as defined (in addition to globals, etc.).
|
||
* Defaults to an empty array.
|
||
*/
|
||
definedTypes?: string[];
|
||
/**
|
||
* Whether to disable reporting of errors. Defaults to
|
||
* `false`. This may be set to `true` in order to take advantage of only
|
||
* marking defined variables as used or checking used typedefs.
|
||
*/
|
||
disableReporting?: boolean;
|
||
/**
|
||
* Whether to mark variables as used for the purposes
|
||
* of the `no-unused-vars` rule when they are not found to be undefined.
|
||
* Defaults to `true`. May be set to `false` to enforce a practice of not
|
||
* importing types unless used in code.
|
||
*/
|
||
markVariablesAsUsed?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Prefer `@import` tags to inline `import()` statements. */
|
||
"jsdoc/prefer-import-tag":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Whether or not to enable the fixer to add `@import` tags.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* Whether to allow `import()` statements within `@typedef`
|
||
*/
|
||
exemptTypedefs?: boolean;
|
||
/**
|
||
* What kind of `@import` to generate when no matching `@typedef` or `@import` is found
|
||
*/
|
||
outputType?: "named-import" | "namespaced-import";
|
||
}
|
||
];
|
||
|
||
/** Reports use of `any` or `*` type */
|
||
"jsdoc/reject-any-type": [];
|
||
|
||
/** Reports use of `Function` type */
|
||
"jsdoc/reject-function-type": [];
|
||
|
||
/** Requires that each JSDoc line starts with an `*`. */
|
||
"jsdoc/require-asterisk-prefix":
|
||
| []
|
||
| ["always" | "never" | "any"]
|
||
| [
|
||
"always" | "never" | "any",
|
||
{
|
||
/**
|
||
* If you want different values to apply to specific tags, you may use
|
||
* the `tags` option object. The keys are `always`, `never`, or `any` and
|
||
* the values are arrays of tag names or the special value `*description`
|
||
* which applies to the main JSDoc block description.
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/require-asterisk-prefix': ['error', 'always', {
|
||
* tags: {
|
||
* always: ['*description'],
|
||
* any: ['example', 'license'],
|
||
* never: ['copyright']
|
||
* }
|
||
* }]
|
||
* }
|
||
* ```
|
||
*/
|
||
tags?: {
|
||
/**
|
||
* If it is `"always"` then a problem is raised when there is no asterisk
|
||
* prefix on a given JSDoc line.
|
||
*/
|
||
always?: string[];
|
||
/**
|
||
* No problem is raised regardless of asterisk presence or non-presence.
|
||
*/
|
||
any?: string[];
|
||
/**
|
||
* If it is `"never"` then a problem is raised
|
||
* when there is an asterisk present.
|
||
*/
|
||
never?: string[];
|
||
};
|
||
}
|
||
];
|
||
|
||
/** Requires that all functions (and potentially other contexts) have a description. */
|
||
"jsdoc/require-description":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* A value indicating whether `constructor`s should be
|
||
* checked. Defaults to `true`.
|
||
*/
|
||
checkConstructors?: boolean;
|
||
/**
|
||
* A value indicating whether getters should be checked.
|
||
* Defaults to `true`.
|
||
*/
|
||
checkGetters?: boolean;
|
||
/**
|
||
* A value indicating whether setters should be checked.
|
||
* Defaults to `true`.
|
||
*/
|
||
checkSetters?: boolean;
|
||
/**
|
||
* Set to an array of strings representing the AST context
|
||
* where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6
|
||
* classes).
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`,
|
||
* `FunctionDeclaration`, `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* Whether to accept implicit descriptions (`"body"`) or
|
||
* `@description` tags (`"tag"`) as satisfying the rule. Set to `"any"` to
|
||
* accept either style. Defaults to `"body"`.
|
||
*/
|
||
descriptionStyle?: "body" | "tag" | "any";
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the
|
||
* document block avoids the need for a `@description`. Defaults to an
|
||
* array with `inheritdoc`. If you set this array, it will overwrite the
|
||
* default, so be sure to add back `inheritdoc` if you wish its presence
|
||
* to cause exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
}
|
||
];
|
||
|
||
/** Requires that block description, explicit `@description`, and `@param`/`@returns` tag descriptions are written in complete sentences. */
|
||
"jsdoc/require-description-complete-sentence":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* 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.
|
||
*/
|
||
abbreviations?: string[];
|
||
/**
|
||
* When `false` (the new default), we will not assume capital letters after
|
||
* newlines are an incorrect way to end the sentence (they may be proper
|
||
* nouns, for example).
|
||
*/
|
||
newlineBeforeCapsAssumesBadSentenceEnd?: boolean;
|
||
/**
|
||
* If you want additional tags to be checked for their descriptions, you may
|
||
* add them within this option.
|
||
*
|
||
* ```js
|
||
* {
|
||
* 'jsdoc/require-description-complete-sentence': ['error', {
|
||
* tags: ['see', 'copyright']
|
||
* }]
|
||
* }
|
||
* ```
|
||
*
|
||
* The tags `@param`/`@arg`/`@argument` and `@property`/`@prop` will be properly
|
||
* parsed to ensure that the checked "description" text includes only the text
|
||
* after the name.
|
||
*
|
||
* All other tags will treat the text following the tag name, a space, and
|
||
* an optional curly-bracketed type expression (and another space) as part of
|
||
* its "description" (e.g., for `@returns {someType} some description`, the
|
||
* description is `some description` while for `@some-tag xyz`, the description
|
||
* is `xyz`).
|
||
*/
|
||
tags?: string[];
|
||
}
|
||
];
|
||
|
||
/** Requires that all functions (and potentially other contexts) have examples. */
|
||
"jsdoc/require-example":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* A value indicating whether `constructor`s should be checked.
|
||
* Defaults to `true`.
|
||
*/
|
||
checkConstructors?: boolean;
|
||
/**
|
||
* A value indicating whether getters should be checked. Defaults to `false`.
|
||
*/
|
||
checkGetters?: boolean;
|
||
/**
|
||
* A value indicating whether setters should be checked. Defaults to `false`.
|
||
*/
|
||
checkSetters?: boolean;
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
* (e.g., `ClassDeclaration` for ES6 classes).
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want the rule to apply to any
|
||
* JSDoc block throughout your files.
|
||
*
|
||
* See the ["AST and Selectors"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* A boolean on whether to enable the fixer (which adds an empty `@example` block).
|
||
* Defaults to `true`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the document
|
||
* block avoids the need for an `@example`. Defaults to an array with
|
||
* `inheritdoc`. If you set this array, it will overwrite the default,
|
||
* so be sure to add back `inheritdoc` if you wish its presence to cause
|
||
* exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
/**
|
||
* Boolean to indicate that no-argument functions should not be reported for
|
||
* missing `@example` declarations.
|
||
*/
|
||
exemptNoArguments?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file. */
|
||
"jsdoc/require-file-overview":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* The keys of this object are tag names, and the values are configuration
|
||
* objects indicating what will be checked for these whole-file tags.
|
||
*
|
||
* Each configuration object has 3 potential boolean keys (which default
|
||
* to `false` when this option is supplied).
|
||
*
|
||
* 1. `mustExist` - enforces that all files have a `@file`, `@fileoverview`, or `@overview` tag.
|
||
* 2. `preventDuplicates` - enforces that duplicate file overview tags within a given file will be reported
|
||
* 3. `initialCommentsOnly` - reports file overview tags which are not, as per
|
||
* [the docs](https://jsdoc.app/tags-file.html), "at the beginning of
|
||
* the file"–where beginning of the file is interpreted in this rule
|
||
* as being when the overview tag is not preceded by anything other than
|
||
* a comment.
|
||
*
|
||
* When no `tags` is present, the default is:
|
||
*
|
||
* ```json
|
||
* {
|
||
* "file": {
|
||
* "initialCommentsOnly": true,
|
||
* "mustExist": true,
|
||
* "preventDuplicates": true,
|
||
* }
|
||
* }
|
||
* ```
|
||
*
|
||
* You can add additional tag names and/or override `file` if you supply this
|
||
* option, e.g., in place of or in addition to `file`, giving other potential
|
||
* file global tags like `@license`, `@copyright`, `@author`, `@module` or
|
||
* `@exports`, optionally restricting them to a single use or preventing them
|
||
* from being preceded by anything besides comments.
|
||
*
|
||
* For example:
|
||
*
|
||
* ```js
|
||
* {
|
||
* "license": {
|
||
* "mustExist": true,
|
||
* "preventDuplicates": true,
|
||
* }
|
||
* }
|
||
* ```
|
||
*
|
||
* This would require one and only one `@license` in the file, though because
|
||
* `initialCommentsOnly` is absent and defaults to `false`, the `@license`
|
||
* can be anywhere.
|
||
*
|
||
* In the case of `@license`, you can use this rule along with the
|
||
* `check-values` rule (with its `allowedLicenses` or `licensePattern` options),
|
||
* to enforce a license whitelist be present on every JS file.
|
||
*
|
||
* Note that if you choose to use `preventDuplicates` with `license`, you still
|
||
* have a way to allow multiple licenses for the whole page by using the SPDX
|
||
* "AND" expression, e.g., `@license (MIT AND GPL-3.0)`.
|
||
*
|
||
* Note that the tag names are the main JSDoc tag name, so you should use `file`
|
||
* in this configuration object regardless of whether you have configured
|
||
* `fileoverview` instead of `file` on `tagNamePreference` (i.e., `fileoverview`
|
||
* will be checked, but you must use `file` on the configuration object).
|
||
*/
|
||
tags?: {
|
||
/**
|
||
* This interface was referenced by `undefined`'s JSON-Schema definition
|
||
* via the `patternProperty` ".*".
|
||
*/
|
||
[k: string]: {
|
||
initialCommentsOnly?: boolean;
|
||
mustExist?: boolean;
|
||
preventDuplicates?: boolean;
|
||
};
|
||
};
|
||
}
|
||
];
|
||
|
||
/** Requires a hyphen before the `@param` description (and optionally before `@property` descriptions). */
|
||
"jsdoc/require-hyphen-before-param-description":
|
||
| []
|
||
| ["always" | "never"]
|
||
| [
|
||
"always" | "never",
|
||
{
|
||
/**
|
||
* Object whose keys indicate different tags to check for the
|
||
* presence or absence of hyphens; the key value should be "always" or "never",
|
||
* indicating how hyphens are to be applied, e.g., `{property: 'never'}`
|
||
* to ensure `@property` never uses hyphens. A key can also be set as `*`, e.g.,
|
||
* `'*': 'always'` to apply hyphen checking to any tag (besides the preferred
|
||
* `@param` tag which follows the main string option setting and besides any
|
||
* other `tags` entries).
|
||
*/
|
||
tags?:
|
||
| {
|
||
/**
|
||
* This interface was referenced by `undefined`'s JSON-Schema definition
|
||
* via the `patternProperty` ".*".
|
||
*/
|
||
[k: string]: "always" | "never";
|
||
}
|
||
| "any";
|
||
}
|
||
];
|
||
|
||
/** Checks for presence of JSDoc comments, on functions and potentially other contexts (optionally limited to exports). */
|
||
"jsdoc/require-jsdoc":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Normally, when `FunctionExpression` is checked, additional checks are
|
||
* added to check the parent contexts where reporting is likely to be desired. If you really
|
||
* want to check *all* function expressions, then set this to `true`.
|
||
*/
|
||
checkAllFunctionExpressions?: boolean;
|
||
/**
|
||
* 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.
|
||
*/
|
||
checkConstructors?: boolean;
|
||
/**
|
||
* A value indicating whether getters should be checked. Besides setting as a
|
||
* boolean, this option can be set to the string `"no-setter"` to indicate that
|
||
* 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`.
|
||
*/
|
||
checkGetters?: boolean | "no-setter";
|
||
/**
|
||
* A value indicating whether setters should be checked. Besides setting as a
|
||
* boolean, this option can be set to the string `"no-getter"` to indicate that
|
||
* 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`.
|
||
*/
|
||
checkSetters?: boolean | "no-getter";
|
||
/**
|
||
* Set this to an array of strings or objects representing the additional AST
|
||
* contexts where you wish the rule to be applied (e.g., `Property` for
|
||
* properties). If specified as an object, it should have a `context` property
|
||
* and can have an `inlineCommentBlock` property which, if set to `true`, will
|
||
* add an inline `/** * /` instead of the regular, multi-line, indented jsdoc
|
||
* block which will otherwise be added. Defaults to an empty array. Contexts
|
||
* may also have their own `minLineCount` property which is an integer
|
||
* indicating a minimum number of lines expected for a node in order
|
||
* for it to require documentation.
|
||
*
|
||
* 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
context?: string;
|
||
inlineCommentBlock?: boolean;
|
||
minLineCount?: number;
|
||
}
|
||
)[];
|
||
/**
|
||
* A boolean on whether to enable the fixer (which adds an empty JSDoc block).
|
||
* Defaults to `true`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* 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).
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
exemptEmptyConstructors?: boolean;
|
||
/**
|
||
* 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).
|
||
*
|
||
* Defaults to `false`.
|
||
*/
|
||
exemptEmptyFunctions?: boolean;
|
||
/**
|
||
* If set to `true` will avoid checking an overloaded function's implementation.
|
||
*
|
||
* Defaults to `false`.
|
||
*/
|
||
exemptOverloadedImplementations?: boolean;
|
||
/**
|
||
* An optional message to add to the inserted JSDoc block. Defaults to the
|
||
* empty string.
|
||
*/
|
||
fixerMessage?: string;
|
||
/**
|
||
* An integer to indicate a minimum number of lines expected for a node in order
|
||
* for it to require documentation. Defaults to `undefined`. This option will
|
||
* apply to any context; see `contexts` for line counts specific to a context.
|
||
*/
|
||
minLineCount?: number;
|
||
/**
|
||
* This option will insist that missing JSDoc blocks are only reported for
|
||
* function bodies / class declarations that are exported from the module.
|
||
* May be a boolean or object. If set to `true`, the defaults below will be
|
||
* used. If unset, JSDoc block reporting will not be limited to exports.
|
||
*
|
||
* This object supports the following optional boolean keys (`false` unless
|
||
* otherwise noted):
|
||
*
|
||
* - `ancestorsOnly` - Optimization to only check node ancestors to check if node is exported
|
||
* - `esm` - ESM exports are checked for JSDoc comments (Defaults to `true`)
|
||
* - `cjs` - CommonJS exports are checked for JSDoc comments (Defaults to `true`)
|
||
* - `window` - Window global exports are checked for JSDoc comments
|
||
*/
|
||
publicOnly?:
|
||
| boolean
|
||
| {
|
||
ancestorsOnly?: boolean;
|
||
cjs?: boolean;
|
||
esm?: boolean;
|
||
window?: boolean;
|
||
};
|
||
/**
|
||
* An object with the following optional boolean keys which all default to
|
||
* `false` except for `FunctionDeclaration` which defaults to `true`.
|
||
*/
|
||
require?: {
|
||
/**
|
||
* Whether to check arrow functions like `() => {}`
|
||
*/
|
||
ArrowFunctionExpression?: boolean;
|
||
/**
|
||
* Whether to check declarations like `class A {}`
|
||
*/
|
||
ClassDeclaration?: boolean;
|
||
/**
|
||
* Whether to check class expressions like `const myClass = class {}`
|
||
*/
|
||
ClassExpression?: boolean;
|
||
/**
|
||
* Whether to check function declarations like `function a {}`
|
||
*/
|
||
FunctionDeclaration?: boolean;
|
||
/**
|
||
* Whether to check function expressions like `const a = function {}`
|
||
*/
|
||
FunctionExpression?: boolean;
|
||
/**
|
||
* Whether to check method definitions like `class A { someMethodDefinition () {} }`
|
||
*/
|
||
MethodDefinition?: boolean;
|
||
};
|
||
/**
|
||
* If `true`, will skip above uncommented overloaded functions to check
|
||
* for a comment block (e.g., at the top of a set of overloaded functions).
|
||
*
|
||
* If `false`, will force each overloaded function to be checked for a
|
||
* comment block.
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
skipInterveningOverloadedDeclarations?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Requires a description for `@next` tags */
|
||
"jsdoc/require-next-description": [];
|
||
|
||
/** Requires a type for `@next` tags */
|
||
"jsdoc/require-next-type": [];
|
||
|
||
/** Requires that all function parameters are documented with a `@param` tag. */
|
||
"jsdoc/require-param":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Numeric to indicate the number at which to begin auto-incrementing roots.
|
||
* Defaults to `0`.
|
||
*/
|
||
autoIncrementBase?: number;
|
||
/**
|
||
* A value indicating whether `constructor`s should be checked. Defaults to
|
||
* `true`.
|
||
*/
|
||
checkConstructors?: boolean;
|
||
/**
|
||
* Whether to require destructured properties. Defaults to `true`.
|
||
*/
|
||
checkDestructured?: boolean;
|
||
/**
|
||
* Whether to check the existence of a corresponding `@param` for root objects
|
||
* of destructured properties (e.g., that for `function ({a, b}) {}`, that there
|
||
* is something like `@param myRootObj` defined that can correspond to
|
||
* the `{a, b}` object parameter).
|
||
*
|
||
* If `checkDestructuredRoots` is `false`, `checkDestructured` will also be
|
||
* 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`.
|
||
*/
|
||
checkDestructuredRoots?: boolean;
|
||
/**
|
||
* A value indicating whether getters should be checked. Defaults to `false`.
|
||
*/
|
||
checkGetters?: boolean;
|
||
/**
|
||
* If set to `true`, will report (and add fixer insertions) for missing rest
|
||
* properties. Defaults to `false`.
|
||
*
|
||
* If set to `true`, note that you can still document the subproperties of the
|
||
* rest property using other jsdoc features, e.g., `@typedef`:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @typedef ExtraOptions
|
||
* * @property innerProp1
|
||
* * @property innerProp2
|
||
* * /
|
||
*
|
||
* /**
|
||
* * @param cfg
|
||
* * @param cfg.num
|
||
* * @param {ExtraOptions} extra
|
||
* * /
|
||
* function quux ({num, ...extra}) {
|
||
* }
|
||
* ```
|
||
*
|
||
* Setting this option to `false` (the default) may be useful in cases where
|
||
* you already have separate `@param` definitions for each of the properties
|
||
* within the rest property.
|
||
*
|
||
* For example, with the option disabled, this will not give an error despite
|
||
* `extra` not having any definition:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param cfg
|
||
* * @param cfg.num
|
||
* * /
|
||
* function quux ({num, ...extra}) {
|
||
* }
|
||
* ```
|
||
*
|
||
* Nor will this:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param cfg
|
||
* * @param cfg.num
|
||
* * @param cfg.innerProp1
|
||
* * @param cfg.innerProp2
|
||
* * /
|
||
* function quux ({num, ...extra}) {
|
||
* }
|
||
* ```
|
||
*/
|
||
checkRestProperty?: boolean;
|
||
/**
|
||
* A value indicating whether setters should be checked. Defaults to `false`.
|
||
*/
|
||
checkSetters?: boolean;
|
||
/**
|
||
* When one specifies a type, unless it is of a generic type, like `object`
|
||
* or `array`, it may be considered unnecessary to have that object's
|
||
* destructured components required, especially where generated docs will
|
||
* link back to the specified type. For example:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param {SVGRect} bbox - a SVGRect
|
||
* * /
|
||
* export const bboxToObj = function ({x, y, width, height}) {
|
||
* return {x, y, width, height};
|
||
* };
|
||
* ```
|
||
*
|
||
* By default `checkTypesPattern` is set to
|
||
* `/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/v`,
|
||
* meaning that destructuring will be required only if the type of the `@param`
|
||
* (the text between curly brackets) is a match for "Object" or "Array" (with or
|
||
* without initial caps), "PlainObject", or "GenericObject", "GenericArray" (or
|
||
* if no type is present). So in the above example, the lack of a match will
|
||
* mean that no complaint will be given about the undocumented destructured
|
||
* parameters.
|
||
*
|
||
* Note that the `/` delimiters are optional, but necessary to add flags.
|
||
*
|
||
* Defaults to using (only) the `v` flag, so to add your own flags, encapsulate
|
||
* your expression as a string, but like a literal, e.g., `/^object$/vi`.
|
||
*
|
||
* 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.
|
||
*/
|
||
checkTypesPattern?: string;
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). May be useful for adding such as
|
||
* `TSMethodSignature` in TypeScript or restricting the contexts
|
||
* which are checked.
|
||
*
|
||
* See the ["AST and Selectors"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* Whether to enable the fixer. Defaults to `true`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* Whether to enable the rest element fixer.
|
||
*
|
||
* The fixer will automatically report/insert
|
||
* [JSDoc repeatable parameters](https://jsdoc.app/tags-param.html#multiple-types-and-repeatable-parameters)
|
||
* if missing.
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param {GenericArray} cfg
|
||
* * @param {number} cfg."0"
|
||
* * /
|
||
* function baar ([a, ...extra]) {
|
||
* //
|
||
* }
|
||
* ```
|
||
*
|
||
* ...becomes:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param {GenericArray} cfg
|
||
* * @param {number} cfg."0"
|
||
* * @param {...any} cfg."1"
|
||
* * /
|
||
* function baar ([a, ...extra]) {
|
||
* //
|
||
* }
|
||
* ```
|
||
*
|
||
* Note that the type `any` is included since we don't know of any specific
|
||
* type to use.
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
enableRestElementFixer?: boolean;
|
||
/**
|
||
* Whether to enable the auto-adding of incrementing roots.
|
||
*
|
||
* The default behavior of `true` is for "root" to be auto-inserted for missing
|
||
* roots, followed by a 0-based auto-incrementing number.
|
||
*
|
||
* So for:
|
||
*
|
||
* ```js
|
||
* function quux ({foo}, {bar}, {baz}) {
|
||
* }
|
||
* ```
|
||
*
|
||
* ...the default JSDoc that would be added if the fixer is enabled would be:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param root0
|
||
* * @param root0.foo
|
||
* * @param root1
|
||
* * @param root1.bar
|
||
* * @param root2
|
||
* * @param root2.baz
|
||
* * /
|
||
* ```
|
||
*
|
||
* Has no effect if `enableFixer` is set to `false`.
|
||
*/
|
||
enableRootFixer?: boolean;
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the document block
|
||
* avoids the need for a `@param`. Defaults to an array with
|
||
* `inheritdoc`. If you set this array, it will overwrite the default,
|
||
* so be sure to add back `inheritdoc` if you wish its presence to cause
|
||
* exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
/**
|
||
* Set to `true` to ignore reporting when all params are missing. Defaults to
|
||
* `false`.
|
||
*/
|
||
ignoreWhenAllParamsMissing?: boolean;
|
||
/**
|
||
* Set if you wish TypeScript interfaces to exempt checks for the existence of
|
||
* `@param`'s.
|
||
*
|
||
* Will check for a type defining the function itself (on a variable
|
||
* declaration) or if there is a single destructured object with a type.
|
||
* Defaults to `false`.
|
||
*/
|
||
interfaceExemptsParamsCheck?: boolean;
|
||
/**
|
||
* An array of root names to use in the fixer when roots are missing. Defaults
|
||
* to `['root']`. Note that only when all items in the array besides the last
|
||
* are exhausted will auto-incrementing occur. So, with
|
||
* `unnamedRootBase: ['arg', 'config']`, the following:
|
||
*
|
||
* ```js
|
||
* function quux ({foo}, [bar], {baz}) {
|
||
* }
|
||
* ```
|
||
*
|
||
* ...will get the following JSDoc block added:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @param arg
|
||
* * @param arg.foo
|
||
* * @param config0
|
||
* * @param config0."0" (`bar`)
|
||
* * @param config1
|
||
* * @param config1.baz
|
||
* * /
|
||
* ```
|
||
*/
|
||
unnamedRootBase?: string[];
|
||
/**
|
||
* Set to `true` if you wish to expect documentation of properties on objects
|
||
* supplied as default values. Defaults to `false`.
|
||
*/
|
||
useDefaultObjectProperties?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Requires that each `@param` tag has a `description` value. */
|
||
"jsdoc/require-param-description":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* The description string to set by default for destructured roots. Defaults to
|
||
* "The root object".
|
||
*/
|
||
defaultDestructuredRootDescription?: string;
|
||
/**
|
||
* Whether to set a default destructured root description. For example, you may
|
||
* wish to avoid manually having to set the description for a `@param`
|
||
* corresponding to a destructured root object as it should always be the same
|
||
* type of object. Uses `defaultDestructuredRootDescription` for the description
|
||
* string. Defaults to `false`.
|
||
*/
|
||
setDefaultDestructuredRootDescription?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Requires that all `@param` tags have names. */
|
||
"jsdoc/require-param-name":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** Requires that each `@param` tag has a type value (in curly brackets). */
|
||
"jsdoc/require-param-type":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* The type string to set by default for destructured roots. Defaults to "object".
|
||
*/
|
||
defaultDestructuredRootType?: string;
|
||
/**
|
||
* Whether to set a default destructured root type. For example, you may wish
|
||
* to avoid manually having to set the type for a `@param`
|
||
* corresponding to a destructured root object as it is always going to be an
|
||
* object. Uses `defaultDestructuredRootType` for the type string. Defaults to
|
||
* `false`.
|
||
*/
|
||
setDefaultDestructuredRootType?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Requires that all `@typedef` and `@namespace` tags have `@property` when their type is a plain `object`, `Object`, or `PlainObject`. */
|
||
"jsdoc/require-property": [];
|
||
|
||
/** Requires that each `@property` tag has a `description` value. */
|
||
"jsdoc/require-property-description": [];
|
||
|
||
/** Requires that all `@property` tags have names. */
|
||
"jsdoc/require-property-name": [];
|
||
|
||
/** Requires that each `@property` tag has a type value (in curly brackets). */
|
||
"jsdoc/require-property-type": [];
|
||
|
||
/** Requires that Promise rejections are documented with `@rejects` tags. */
|
||
"jsdoc/require-rejects":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context
|
||
* (or objects with optional `context` and `comment` properties) where you wish
|
||
* the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`).
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the
|
||
* document block avoids the need for a `@rejects`. Defaults to an array
|
||
* with `abstract`, `virtual`, and `type`. If you set this array, it will overwrite the default,
|
||
* so be sure to add back those tags if you wish their presence to cause
|
||
* exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
}
|
||
];
|
||
|
||
/** Requires that returns are documented with `@returns`. */
|
||
"jsdoc/require-returns":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* A value indicating whether `constructor`s should
|
||
* be checked for `@returns` tags. Defaults to `false`.
|
||
*/
|
||
checkConstructors?: boolean;
|
||
/**
|
||
* Boolean to determine whether getter methods should
|
||
* be checked for `@returns` tags. Defaults to `true`.
|
||
*/
|
||
checkGetters?: boolean;
|
||
/**
|
||
* Set this to an array of strings representing the AST context
|
||
* (or objects with optional `context` and `comment` properties) where you wish
|
||
* the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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`). This
|
||
* rule will only apply on non-default contexts when there is such a tag
|
||
* present and the `forceRequireReturn` option is set or if the
|
||
* `forceReturnsWithAsync` option is set with a present `@async` tag
|
||
* (since we are not checking against the actual `return` values in these
|
||
* cases).
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
forceRequireReturn?: boolean;
|
||
}
|
||
)[];
|
||
/**
|
||
* Whether to enable the fixer to add a blank `@returns`.
|
||
* Defaults to `false`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the
|
||
* document block avoids the need for a `@returns`. Defaults to an array
|
||
* with `inheritdoc`. If you set this array, it will overwrite the default,
|
||
* so be sure to add back `inheritdoc` if you wish its presence to cause
|
||
* exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
/**
|
||
* Set to `true` to always insist on
|
||
* `@returns` documentation regardless of implicit or explicit `return`'s
|
||
* in the function. May be desired to flag that a project is aware of an
|
||
* `undefined`/`void` return. Defaults to `false`.
|
||
*/
|
||
forceRequireReturn?: boolean;
|
||
/**
|
||
* By default `async` functions that do not explicitly
|
||
* return a value pass this rule as an `async` function will always return a
|
||
* `Promise`, even if the `Promise` resolves to void. You can force all
|
||
* `async` functions (including ones with an explicit `Promise` but no
|
||
* detected non-`undefined` `resolve` value) to require `@return`
|
||
* documentation by setting `forceReturnsWithAsync` to `true` on the options
|
||
* object. This may be useful for flagging that there has been consideration
|
||
* of return type. Defaults to `false`.
|
||
*/
|
||
forceReturnsWithAsync?: boolean;
|
||
/**
|
||
* This option will insist that missing `@returns` are only reported for
|
||
* function bodies / class declarations that are exported from the module.
|
||
* May be a boolean or object. If set to `true`, the defaults below will be
|
||
* used. If unset, `@returns` reporting will not be limited to exports.
|
||
*
|
||
* This object supports the following optional boolean keys (`false` unless
|
||
* otherwise noted):
|
||
*
|
||
* - `ancestorsOnly` - Optimization to only check node ancestors to check if node is exported
|
||
* - `esm` - ESM exports are checked for `@returns` JSDoc comments (Defaults to `true`)
|
||
* - `cjs` - CommonJS exports are checked for `@returns` JSDoc comments (Defaults to `true`)
|
||
* - `window` - Window global exports are checked for `@returns` JSDoc comments
|
||
*/
|
||
publicOnly?:
|
||
| boolean
|
||
| {
|
||
ancestorsOnly?: boolean;
|
||
cjs?: boolean;
|
||
esm?: boolean;
|
||
window?: boolean;
|
||
};
|
||
}
|
||
];
|
||
|
||
/** Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present). */
|
||
"jsdoc/require-returns-check":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* By default, functions which return a `Promise` that are not
|
||
* detected as resolving with a non-`undefined` value and `async` functions
|
||
* (even ones that do not explicitly return a value, as these are returning a
|
||
* `Promise` implicitly) will be exempted from reporting by this rule.
|
||
* If you wish to insist that only `Promise`'s which resolve to
|
||
* non-`undefined` values or `async` functions with explicit `return`'s will
|
||
* be exempted from reporting (i.e., that `async` functions can be reported
|
||
* if they lack an explicit (non-`undefined`) `return` when a `@returns` is
|
||
* present), you can set `exemptAsync` to `false` on the options object.
|
||
*/
|
||
exemptAsync?: boolean;
|
||
/**
|
||
* Because a generator might be labeled as having a
|
||
* `IterableIterator` `@returns` value (along with an iterator type
|
||
* corresponding to the type of any `yield` statements), projects might wish to
|
||
* leverage `@returns` in generators even without a `return` statement. This
|
||
* option is therefore `true` by default in `typescript` mode (in "jsdoc" mode,
|
||
* one might be more likely to take advantage of `@yields`). Set it to `false`
|
||
* if you wish for a missing `return` to be flagged regardless.
|
||
*/
|
||
exemptGenerators?: boolean;
|
||
/**
|
||
* Whether to check that async functions do not
|
||
* indicate they return non-native types. Defaults to `true`.
|
||
*/
|
||
noNativeTypes?: boolean;
|
||
/**
|
||
* If `true` and no return or
|
||
* resolve value is found, this setting will even insist that reporting occur
|
||
* with `void` or `undefined` (including as an indicated `Promise` type).
|
||
* Unlike `require-returns`, with this option in the rule, one can
|
||
* *discourage* the labeling of `undefined` types. Defaults to `false`.
|
||
*/
|
||
reportMissingReturnForUndefinedTypes?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns). */
|
||
"jsdoc/require-returns-description":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** Requires that `@returns` tag has type value (in curly brackets). */
|
||
"jsdoc/require-returns-type":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context (or an object with
|
||
* optional `context` and `comment` properties) where you wish the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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"](../#advanced-ast-and-selectors)
|
||
* section of our Advanced docs for more on the expected format.
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** Requires tags be present, optionally for specific contexts */
|
||
"jsdoc/require-tags":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* May be an array of either strings or objects with
|
||
* a string `tag` property and `context` string property.
|
||
*/
|
||
tags?: (
|
||
| string
|
||
| {
|
||
context?: string;
|
||
tag?: string;
|
||
[k: string]: unknown;
|
||
}
|
||
)[];
|
||
}
|
||
];
|
||
|
||
/** Requires `@template` tags be present when type parameters are used. */
|
||
"jsdoc/require-template":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the document
|
||
* block avoids the need for a `@template`. Defaults to an array with
|
||
* `inheritdoc`. If you set this array, it will overwrite the default,
|
||
* so be sure to add back `inheritdoc` if you wish its presence to cause
|
||
* exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
/**
|
||
* Requires that each template have its own separate line, i.e., preventing
|
||
* templates of this format:
|
||
*
|
||
* ```js
|
||
* /**
|
||
* * @template T, U, V
|
||
* * /
|
||
* ```
|
||
*
|
||
* Defaults to `false`.
|
||
*/
|
||
requireSeparateTemplates?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Requires a description for `@template` tags */
|
||
"jsdoc/require-template-description": [];
|
||
|
||
/** Requires that throw statements are documented with `@throws` tags. */
|
||
"jsdoc/require-throws":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context
|
||
* (or objects with optional `context` and `comment` properties) where you wish
|
||
* the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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`).
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the
|
||
* document block avoids the need for a `@throws`. Defaults to an array
|
||
* with `inheritdoc`. If you set this array, it will overwrite the default,
|
||
* so be sure to add back `inheritdoc` if you wish its presence to cause
|
||
* exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
}
|
||
];
|
||
|
||
/** Requires a description for `@throws` tags */
|
||
"jsdoc/require-throws-description": [];
|
||
|
||
/** Requires a type for `@throws` tags */
|
||
"jsdoc/require-throws-type": [];
|
||
|
||
/** Requires yields are documented with `@yields` tags. */
|
||
"jsdoc/require-yields":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set this to an array of strings representing the AST context
|
||
* (or objects with optional `context` and `comment` properties) where you wish
|
||
* the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`). Set to `"any"` if you want
|
||
* the rule to apply to any JSDoc block throughout 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`). This
|
||
* rule will only apply on non-default contexts when there is such a tag
|
||
* present and the `forceRequireYields` option is set or if the
|
||
* `withGeneratorTag` option is set with a present `@generator` tag
|
||
* (since we are not checking against the actual `yield` values in these
|
||
* cases).
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* Array of tags (e.g., `['type']`) whose presence on the
|
||
* document block avoids the need for a `@yields`. Defaults to an array
|
||
* with `inheritdoc`. If you set this array, it will overwrite the default,
|
||
* so be sure to add back `inheritdoc` if you wish its presence to cause
|
||
* exemption of the rule.
|
||
*/
|
||
exemptedBy?: string[];
|
||
/**
|
||
* Set to `true` to always insist on
|
||
* `@next` documentation even if there are no `yield` statements in the
|
||
* function or none return values. May be desired to flag that a project is
|
||
* aware of the expected yield return being `undefined`. Defaults to `false`.
|
||
*/
|
||
forceRequireNext?: boolean;
|
||
/**
|
||
* Set to `true` to always insist on
|
||
* `@yields` documentation for generators even if there are only
|
||
* expressionless `yield` statements in the function. May be desired to flag
|
||
* that a project is aware of an `undefined`/`void` yield. Defaults to
|
||
* `false`.
|
||
*/
|
||
forceRequireYields?: boolean;
|
||
/**
|
||
* If `true`, this option will insist that any use of a `yield` return
|
||
* value (e.g., `const rv = yield;` or `const rv = yield value;`) has a
|
||
* (non-standard) `@next` tag (in addition to any `@yields` tag) so as to be
|
||
* able to document the type expected to be supplied into the iterator
|
||
* (the `Generator` iterator that is returned by the call to the generator
|
||
* function) to the iterator (e.g., `it.next(value)`). The tag will not be
|
||
* expected if the generator function body merely has plain `yield;` or
|
||
* `yield value;` statements without returning the values. Defaults to
|
||
* `false`.
|
||
*/
|
||
next?: boolean;
|
||
/**
|
||
* If a `@generator` tag is present on a block, require
|
||
* (non-standard ) `@next` (see `next` option). This will require using `void`
|
||
* or `undefined` in cases where generators do not use the `next()`-supplied
|
||
* incoming `yield`-returned value. Defaults to `false`. See `contexts` to
|
||
* `any` if you want to catch `@generator` with `@callback` or such not
|
||
* attached to a function.
|
||
*/
|
||
nextWithGeneratorTag?: boolean;
|
||
/**
|
||
* If a `@generator` tag is present on a block, require
|
||
* `@yields`/`@yield`. Defaults to `true`. See `contexts` to `any` if you want
|
||
* to catch `@generator` with `@callback` or such not attached to a function.
|
||
*/
|
||
withGeneratorTag?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Ensures that if a `@yields` is present that a `yield` (or `yield` with a value) is present in the function body (or that if a `@next` is present that there is a yield with a return value present). */
|
||
"jsdoc/require-yields-check":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Avoids checking the function body and merely insists
|
||
* that all generators have `@yields`. This can be an optimization with the
|
||
* ESLint `require-yield` rule, as that rule already ensures a `yield` is
|
||
* present in generators, albeit assuming the generator is not empty).
|
||
* Defaults to `false`.
|
||
*/
|
||
checkGeneratorsOnly?: boolean;
|
||
/**
|
||
* Set this to an array of strings representing the AST context
|
||
* (or objects with optional `context` and `comment` properties) where you wish
|
||
* the rule to be applied.
|
||
*
|
||
* `context` defaults to `any` and `comment` defaults to no specific comment context.
|
||
*
|
||
* Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
|
||
* `FunctionExpression`).
|
||
*/
|
||
contexts?: (
|
||
| string
|
||
| {
|
||
comment?: string;
|
||
context?: string;
|
||
}
|
||
)[];
|
||
/**
|
||
* If `true`, this option will insist that any use of a (non-standard)
|
||
* `@next` tag (in addition to any `@yields` tag) will be matched by a `yield`
|
||
* which uses a return value in the body of the generator (e.g.,
|
||
* `const rv = yield;` or `const rv = yield value;`). This (non-standard)
|
||
* tag is intended to be used to indicate a type and/or description of
|
||
* the value expected to be supplied by the user when supplied to the iterator
|
||
* by its `next` method, as with `it.next(value)` (with the iterator being
|
||
* the `Generator` iterator that is returned by the call to the generator
|
||
* function). This option will report an error if the generator function body
|
||
* merely has plain `yield;` or `yield value;` statements without returning
|
||
* the values. Defaults to `false`.
|
||
*/
|
||
next?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Requires a description for `@yields` tags */
|
||
"jsdoc/require-yields-description": [];
|
||
|
||
/** Requires a type for `@yields` tags */
|
||
"jsdoc/require-yields-type": [];
|
||
|
||
/** Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. */
|
||
"jsdoc/sort-tags":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Defaults to `false`. Alphabetizes any items not within `tagSequence` after any
|
||
* items within `tagSequence` (or in place of the special `-other` pseudo-tag)
|
||
* are sorted.
|
||
*
|
||
* If you want all your tags alphabetized, you can supply an empty array for
|
||
* `tagSequence` along with setting this option to `true`.
|
||
*/
|
||
alphabetizeExtras?: boolean;
|
||
/**
|
||
* Indicates the number of lines to be added between tag groups. Defaults to 1.
|
||
* Do not set to 0 or 2+ if you are using `tag-lines` and `"always"` and do not
|
||
* set to 1+ if you are using `tag-lines` and `"never"`.
|
||
*/
|
||
linesBetween?: number;
|
||
/**
|
||
* Whether to enable reporting and fixing of line breaks within tags of a given
|
||
* tag group. Defaults to `true` which will remove any line breaks at the end of
|
||
* such tags. Do not use with `true` if you are using `tag-lines` and `always`.
|
||
*/
|
||
reportIntraTagGroupSpacing?: boolean;
|
||
/**
|
||
* Whether to enable reporting and fixing of line breaks between tag groups
|
||
* as set by `linesBetween`. Defaults to `true`. Note that the very last tag
|
||
* will not have spacing applied regardless. For adding line breaks there, you
|
||
* may wish to use the `endLines` option of the `tag-lines` rule.
|
||
*/
|
||
reportTagGroupSpacing?: boolean;
|
||
/**
|
||
* Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.
|
||
*/
|
||
tagExceptions?: {
|
||
/**
|
||
* This interface was referenced by `undefined`'s JSON-Schema definition
|
||
* via the `patternProperty` ".*".
|
||
*/
|
||
[k: string]: number;
|
||
};
|
||
/**
|
||
* An array of tag group objects indicating the preferred sequence for sorting tags.
|
||
*
|
||
* Each item in the array should be an object with a `tags` property set to an array
|
||
* of tag names.
|
||
*
|
||
* Tag names earlier in the list will be arranged first. The relative position of
|
||
* tags of the same name will not be changed.
|
||
*
|
||
* Earlier groups will also be arranged before later groups, but with the added
|
||
* feature that additional line breaks may be added between (or before or after)
|
||
* such groups (depending on the setting of `linesBetween`).
|
||
*
|
||
* Tag names not in the list will be grouped together at the end. The pseudo-tag
|
||
* `-other` can be used to place them anywhere else if desired. The tags will be
|
||
* placed in their order of appearance, or alphabetized if `alphabetizeExtras`
|
||
* is enabled, see more below about that option.
|
||
*
|
||
* Defaults to the array below (noting that it is just a single tag group with
|
||
* no lines between groups by default).
|
||
*
|
||
* Please note that this order is still experimental, so if you want to retain
|
||
* a fixed order that doesn't change into the future, supply your own
|
||
* `tagSequence`.
|
||
*
|
||
* ```js
|
||
* [{tags: [
|
||
* // Brief descriptions
|
||
* 'summary',
|
||
* 'typeSummary',
|
||
*
|
||
* // Module/file-level
|
||
* 'module',
|
||
* 'exports',
|
||
* 'file',
|
||
* 'fileoverview',
|
||
* 'overview',
|
||
* 'import',
|
||
*
|
||
* // Identifying (name, type)
|
||
* 'typedef',
|
||
* 'interface',
|
||
* 'record',
|
||
* 'template',
|
||
* 'name',
|
||
* 'kind',
|
||
* 'type',
|
||
* 'alias',
|
||
* 'external',
|
||
* 'host',
|
||
* 'callback',
|
||
* 'func',
|
||
* 'function',
|
||
* 'method',
|
||
* 'class',
|
||
* 'constructor',
|
||
*
|
||
* // Relationships
|
||
* 'modifies',
|
||
* 'mixes',
|
||
* 'mixin',
|
||
* 'mixinClass',
|
||
* 'mixinFunction',
|
||
* 'namespace',
|
||
* 'borrows',
|
||
* 'constructs',
|
||
* 'lends',
|
||
* 'implements',
|
||
* 'requires',
|
||
*
|
||
* // Long descriptions
|
||
* 'desc',
|
||
* 'description',
|
||
* 'classdesc',
|
||
* 'tutorial',
|
||
* 'copyright',
|
||
* 'license',
|
||
*
|
||
* // Simple annotations
|
||
* 'const',
|
||
* 'constant',
|
||
* 'final',
|
||
* 'global',
|
||
* 'readonly',
|
||
* 'abstract',
|
||
* 'virtual',
|
||
* 'var',
|
||
* 'member',
|
||
* 'memberof',
|
||
* 'memberof!',
|
||
* 'inner',
|
||
* 'instance',
|
||
* 'inheritdoc',
|
||
* 'inheritDoc',
|
||
* 'override',
|
||
* 'hideconstructor',
|
||
*
|
||
* // Core function/object info
|
||
* 'param',
|
||
* 'arg',
|
||
* 'argument',
|
||
* 'prop',
|
||
* 'property',
|
||
* 'return',
|
||
* 'returns',
|
||
*
|
||
* // Important behavior details
|
||
* 'async',
|
||
* 'generator',
|
||
* 'default',
|
||
* 'defaultvalue',
|
||
* 'enum',
|
||
* 'augments',
|
||
* 'extends',
|
||
* 'throws',
|
||
* 'exception',
|
||
* 'yield',
|
||
* 'yields',
|
||
* 'event',
|
||
* 'fires',
|
||
* 'emits',
|
||
* 'listens',
|
||
* 'this',
|
||
*
|
||
* // Access
|
||
* 'static',
|
||
* 'private',
|
||
* 'protected',
|
||
* 'public',
|
||
* 'access',
|
||
* 'package',
|
||
*
|
||
* '-other',
|
||
*
|
||
* // Supplementary descriptions
|
||
* 'see',
|
||
* 'example',
|
||
*
|
||
* // METADATA
|
||
*
|
||
* // Other Closure (undocumented) metadata
|
||
* 'closurePrimitive',
|
||
* 'customElement',
|
||
* 'expose',
|
||
* 'hidden',
|
||
* 'idGenerator',
|
||
* 'meaning',
|
||
* 'ngInject',
|
||
* 'owner',
|
||
* 'wizaction',
|
||
*
|
||
* // Other Closure (documented) metadata
|
||
* 'define',
|
||
* 'dict',
|
||
* 'export',
|
||
* 'externs',
|
||
* 'implicitCast',
|
||
* 'noalias',
|
||
* 'nocollapse',
|
||
* 'nocompile',
|
||
* 'noinline',
|
||
* 'nosideeffects',
|
||
* 'polymer',
|
||
* 'polymerBehavior',
|
||
* 'preserve',
|
||
* 'struct',
|
||
* 'suppress',
|
||
* 'unrestricted',
|
||
*
|
||
* // @homer0/prettier-plugin-jsdoc metadata
|
||
* 'category',
|
||
*
|
||
* // Non-Closure metadata
|
||
* 'ignore',
|
||
* 'author',
|
||
* 'version',
|
||
* 'variation',
|
||
* 'since',
|
||
* 'deprecated',
|
||
* 'todo',
|
||
* ]}];
|
||
* ```
|
||
*/
|
||
tagSequence?: {
|
||
/**
|
||
* See description on `tagSequence`.
|
||
*/
|
||
tags?: string[];
|
||
}[];
|
||
}
|
||
];
|
||
|
||
/** Enforces lines (or no lines) before, after, or between tags. */
|
||
"jsdoc/tag-lines":
|
||
| []
|
||
| ["always" | "any" | "never"]
|
||
| [
|
||
"always" | "any" | "never",
|
||
{
|
||
/**
|
||
* Set to `false` and use with "always" to indicate the normal lines to be
|
||
* added after tags should not be added after the final tag.
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
applyToEndTag?: boolean;
|
||
/**
|
||
* Use with "always" to indicate the number of lines to require be present.
|
||
*
|
||
* Defaults to 1.
|
||
*/
|
||
count?: number;
|
||
/**
|
||
* If not set to `null`, will enforce end lines to the given count on the
|
||
* final tag only.
|
||
*
|
||
* Defaults to `0`.
|
||
*/
|
||
endLines?: number | null;
|
||
/**
|
||
* If not set to `null`, will enforce a maximum number of lines to the given count anywhere in the block description.
|
||
*
|
||
* Note that if non-`null`, `maxBlockLines` must be greater than or equal to `startLines`.
|
||
*
|
||
* Defaults to `null`.
|
||
*/
|
||
maxBlockLines?: number | null;
|
||
/**
|
||
* If not set to `null`, will enforce end lines to the given count before the
|
||
* first tag only, unless there is only whitespace content, in which case,
|
||
* a line count will not be enforced.
|
||
*
|
||
* Defaults to `0`.
|
||
*/
|
||
startLines?: number | null;
|
||
/**
|
||
* Overrides the default behavior depending on specific tags.
|
||
*
|
||
* An object whose keys are tag names and whose values are objects with the
|
||
* following keys:
|
||
*
|
||
* 1. `lines` - Set to `always`, `never`, or `any` to override.
|
||
* 2. `count` - Overrides main `count` (for "always")
|
||
*
|
||
* Defaults to empty object.
|
||
*/
|
||
tags?: {
|
||
/**
|
||
* This interface was referenced by `undefined`'s JSON-Schema definition
|
||
* via the `patternProperty` ".*".
|
||
*/
|
||
[k: string]: {
|
||
count?: number;
|
||
lines?: "always" | "never" | "any";
|
||
};
|
||
};
|
||
}
|
||
];
|
||
|
||
/** Auto-escape certain characters that are input within block and tag descriptions. */
|
||
"jsdoc/text-escaping":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* This option escapes all `<` and `&` characters (except those followed by
|
||
* whitespace which are treated as literals by Visual Studio Code). Defaults to
|
||
* `false`.
|
||
*/
|
||
escapeHTML?: boolean;
|
||
/**
|
||
* This option escapes the first backtick (`` ` ``) in a paired sequence.
|
||
* Defaults to `false`.
|
||
*/
|
||
escapeMarkdown?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Prefers either function properties or method signatures */
|
||
"jsdoc/ts-method-signature-style":
|
||
| []
|
||
| ["method" | "property"]
|
||
| [
|
||
"method" | "property",
|
||
{
|
||
/**
|
||
* Whether to enable the fixer. Defaults to `true`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Warns against use of the empty object type */
|
||
"jsdoc/ts-no-empty-object-type": [];
|
||
|
||
/** Catches unnecessary template expressions such as string expressions within a template literal. */
|
||
"jsdoc/ts-no-unnecessary-template-expression":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Whether to enable the fixer. Defaults to `true`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Prefers function types over call signatures when there are no other properties. */
|
||
"jsdoc/ts-prefer-function-type":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Whether to enable the fixer or not
|
||
*/
|
||
enableFixer?: boolean;
|
||
}
|
||
];
|
||
|
||
/** Formats JSDoc type values. */
|
||
"jsdoc/type-formatting":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Determines how array generics are represented. Set to `angle` for the style `Array<type>` or `square` for the style `type[]`. Defaults to "square".
|
||
*/
|
||
arrayBrackets?: "angle" | "square";
|
||
/**
|
||
* The space character (if any) to use after return markers (`=>`). Defaults to " ".
|
||
*/
|
||
arrowFunctionPostReturnMarkerSpacing?: string;
|
||
/**
|
||
* The space character (if any) to use before return markers (`=>`). Defaults to " ".
|
||
*/
|
||
arrowFunctionPreReturnMarkerSpacing?: string;
|
||
/**
|
||
* Whether to enable the fixer. Defaults to `true`.
|
||
*/
|
||
enableFixer?: boolean;
|
||
/**
|
||
* The space character (if any) to use between function or class parameters. Defaults to " ".
|
||
*/
|
||
functionOrClassParameterSpacing?: string;
|
||
/**
|
||
* The space character (if any) to use after a generic expression in a function or class. Defaults to "".
|
||
*/
|
||
functionOrClassPostGenericSpacing?: string;
|
||
/**
|
||
* The space character (if any) to use after return markers (`:`). Defaults to "".
|
||
*/
|
||
functionOrClassPostReturnMarkerSpacing?: string;
|
||
/**
|
||
* The space character (if any) to use before return markers (`:`). Defaults to "".
|
||
*/
|
||
functionOrClassPreReturnMarkerSpacing?: string;
|
||
/**
|
||
* The space character (if any) to use between type parameters in a function or class. Defaults to " ".
|
||
*/
|
||
functionOrClassTypeParameterSpacing?: string;
|
||
/**
|
||
* The space character (if any) to use between elements in generics and tuples. Defaults to " ".
|
||
*/
|
||
genericAndTupleElementSpacing?: string;
|
||
/**
|
||
* Boolean value of whether to use a dot before the angled brackets of a generic (e.g., `SomeType.<AnotherType>`). Defaults to `false`.
|
||
*/
|
||
genericDot?: boolean;
|
||
/**
|
||
* The amount of spacing (if any) after the colon of a key-value or object-field pair. Defaults to " ".
|
||
*/
|
||
keyValuePostColonSpacing?: string;
|
||
/**
|
||
* The amount of spacing (if any) immediately after keys in a key-value or object-field pair. Defaults to "".
|
||
*/
|
||
keyValuePostKeySpacing?: string;
|
||
/**
|
||
* The amount of spacing (if any) after the optional operator (`?`) in a key-value or object-field pair. Defaults to "".
|
||
*/
|
||
keyValuePostOptionalSpacing?: string;
|
||
/**
|
||
* The amount of spacing (if any) after a variadic operator (`...`) in a key-value pair. Defaults to "".
|
||
*/
|
||
keyValuePostVariadicSpacing?: string;
|
||
/**
|
||
* The style of quotation mark for surrounding method names when quoted. Defaults to `double`
|
||
*/
|
||
methodQuotes?: "double" | "single";
|
||
/**
|
||
* A string indicating the whitespace to be added on each line preceding an
|
||
* object property-value field. Defaults to the empty string.
|
||
*/
|
||
objectFieldIndent?: string;
|
||
/**
|
||
* Whether and how object field properties should be quoted (e.g., `{"a": string}`).
|
||
* Set to `single`, `double`, or `null`. Defaults to `null` (no quotes unless
|
||
* required due to special characters within the field). Digits will be kept as is,
|
||
* regardless of setting (they can either represent a digit or a string digit).
|
||
*/
|
||
objectFieldQuote?: "double" | "single" | null;
|
||
/**
|
||
* For object properties, specify whether a "semicolon", "comma", "linebreak",
|
||
* "semicolon-and-linebreak", or "comma-and-linebreak" should be used after
|
||
* each object property-value pair.
|
||
*
|
||
* Defaults to `"comma"`.
|
||
*/
|
||
objectFieldSeparator?: "comma" | "comma-and-linebreak" | "linebreak" | "semicolon" | "semicolon-and-linebreak";
|
||
/**
|
||
* Whether `objectFieldSeparator` set to `"semicolon-and-linebreak"` or
|
||
* `"comma-and-linebreak"` should be allowed to optionally drop the linebreak.
|
||
*
|
||
* Defaults to `true`.
|
||
*/
|
||
objectFieldSeparatorOptionalLinebreak?: boolean;
|
||
/**
|
||
* If `separatorForSingleObjectField` is not in effect (i.e., if it is `false`
|
||
* or there are multiple property-value object fields present), this property
|
||
* will determine whether to add punctuation corresponding to the
|
||
* `objectFieldSeparator` (e.g., a semicolon) to the final object field.
|
||
* Defaults to `false`.
|
||
*/
|
||
objectFieldSeparatorTrailingPunctuation?: boolean;
|
||
/**
|
||
* The space character (if any) to use between the equal signs of a default value. Defaults to " ".
|
||
*/
|
||
parameterDefaultValueSpacing?: string;
|
||
/**
|
||
* The space character (if any) to add after a method name. Defaults to "".
|
||
*/
|
||
postMethodNameSpacing?: string;
|
||
/**
|
||
* The space character (if any) to add after "new" in a constructor. Defaults to " ".
|
||
*/
|
||
postNewSpacing?: string;
|
||
/**
|
||
* Whether to apply the `objectFieldSeparator` (e.g., a semicolon) when there
|
||
* is only one property-value object field present. Defaults to `false`.
|
||
*/
|
||
separatorForSingleObjectField?: boolean;
|
||
/**
|
||
* How string literals should be quoted (e.g., `"abc"`). Set to `single`
|
||
* or `double`. Defaults to 'double'.
|
||
*/
|
||
stringQuotes?: "double" | "single";
|
||
/**
|
||
* A string of spaces that will be added immediately after the type's initial
|
||
* curly bracket and immediately before its ending curly bracket. Defaults
|
||
* to the empty string.
|
||
*/
|
||
typeBracketSpacing?: string;
|
||
/**
|
||
* Determines the spacing to add to unions (`|`). Defaults to a single space (`" "`).
|
||
*/
|
||
unionSpacing?: string;
|
||
}
|
||
];
|
||
|
||
/** Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings). */
|
||
"jsdoc/valid-types":
|
||
| []
|
||
| [
|
||
{
|
||
/**
|
||
* Set to `false` to bulk disallow
|
||
* empty name paths with namepath groups 2 and 4 (these might often be
|
||
* expected to have an accompanying name path, though they have some
|
||
* indicative value without one; these may also allow names to be defined
|
||
* in another manner elsewhere in the block); you can use
|
||
* `settings.jsdoc.structuredTags` with the `required` key set to "name" if you
|
||
* wish to require name paths on a tag-by-tag basis. Defaults to `true`.
|
||
*/
|
||
allowEmptyNamepaths?: boolean;
|
||
}
|
||
];
|
||
}
|