diff --git a/.README/README.md b/.README/README.md index 325bd5993..aa93fdfd8 100644 --- a/.README/README.md +++ b/.README/README.md @@ -63,6 +63,7 @@ Finally, enable all of the rules that you would like to use. "jsdoc/no-defaults": 1, "jsdoc/no-types": 1, "jsdoc/no-undefined-types": 1, // Recommended + "jsdoc/require-asterisk-prefix": 1, "jsdoc/require-description": 1, "jsdoc/require-description-complete-sentence": 1, "jsdoc/require-example": 1, @@ -558,6 +559,7 @@ selector). {"gitdown": "include", "file": "./rules/no-restricted-syntax.md"} {"gitdown": "include", "file": "./rules/no-types.md"} {"gitdown": "include", "file": "./rules/no-undefined-types.md"} +{"gitdown": "include", "file": "./rules/require-asterisk-prefix.md"} {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"} {"gitdown": "include", "file": "./rules/require-description.md"} {"gitdown": "include", "file": "./rules/require-example.md"} diff --git a/.README/rules/require-asterisk-prefix.md b/.README/rules/require-asterisk-prefix.md new file mode 100644 index 000000000..9bdd1e1c9 --- /dev/null +++ b/.README/rules/require-asterisk-prefix.md @@ -0,0 +1,40 @@ +### `require-asterisk-prefix` + +Requires that each JSDoc line starts with an `*`. + +#### Options + +This rule allows an optional string argument. If it is `"always"` then a +problem is raised when there is no asterisk prefix on a given jsdoc line. If +it is `"never"` then a problem is raised when there is an asterisk present. +The default value is `"always"`. You may also set the default to `"any"` +and use the `tags` option to apply to specific tags only. + +After the string option, one may add an object with the following. + +##### `tags` + +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'] + } + }] +} +``` + +||| +|---|---| +|Context|everywhere| +|Tags|All or as limited by the `tags` option| +|Options|(a string matching `"always"|"never"` and optional object with `tags`)| + + diff --git a/README.md b/README.md index 50e456336..1c833dcdc 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ JSDoc linting rules for ESLint. * [`no-restricted-syntax`](#eslint-plugin-jsdoc-rules-no-restricted-syntax) * [`no-types`](#eslint-plugin-jsdoc-rules-no-types) * [`no-undefined-types`](#eslint-plugin-jsdoc-rules-no-undefined-types) + * [`require-asterisk-prefix`](#eslint-plugin-jsdoc-rules-require-asterisk-prefix) * [`require-description-complete-sentence`](#eslint-plugin-jsdoc-rules-require-description-complete-sentence) * [`require-description`](#eslint-plugin-jsdoc-rules-require-description) * [`require-example`](#eslint-plugin-jsdoc-rules-require-example) @@ -124,6 +125,7 @@ Finally, enable all of the rules that you would like to use. "jsdoc/no-defaults": 1, "jsdoc/no-types": 1, "jsdoc/no-undefined-types": 1, // Recommended + "jsdoc/require-asterisk-prefix": 1, "jsdoc/require-description": 1, "jsdoc/require-description-complete-sentence": 1, "jsdoc/require-example": 1, @@ -8370,6 +8372,279 @@ class Test { ```` + +### require-asterisk-prefix + +Requires that each JSDoc line starts with an `*`. + + +#### Options + +This rule allows an optional string argument. If it is `"always"` then a +problem is raised when there is no asterisk prefix on a given jsdoc line. If +it is `"never"` then a problem is raised when there is an asterisk present. +The default value is `"always"`. You may also set the default to `"any"` +and use the `tags` option to apply to specific tags only. + +After the string option, one may add an object with the following. + + +##### tags + +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'] + } + }] +} +``` + +||| +|---|---| +|Context|everywhere| +|Tags|All or as limited by the `tags` option| +|Options|(a string matching `"always"|"never"` and optional object with `tags`)| + +The following patterns are considered problems: + +````js + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// Message: Expected JSDoc line to have the prefix. + + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "any",{"tags":{"always":["param"]}}] +// Message: Expected JSDoc line to have the prefix. + + +/** + * Desc + + */ +function quux (foo) { + // with spaces +} +// Message: Expected JSDoc line to have the prefix. + + +/** + * + Desc + */ +function quux (foo) { + // with spaces +} +// Message: Expected JSDoc line to have the prefix. + + +/** + * Desc + * + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never"] +// Message: Expected JSDoc line to have no prefix. + + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "always",{"tags":{"any":["someOtherTag"]}}] +// Message: Expected JSDoc line to have the prefix. + + +/** + * @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never",{"tags":{"always":["someOtherTag"]}}] +// Message: Expected JSDoc line to have no prefix. + + +/** + * @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "always",{"tags":{"never":["param"]}}] +// Message: Expected JSDoc line to have no prefix. + + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never",{"tags":{"always":["param"]}}] +// Message: Expected JSDoc line to have the prefix. + +/** + @param {Number} foo + */function quux (foo) { + // with spaces +} +// Message: Expected JSDoc line to have the prefix. + + +/** + * @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never"] +// Message: Expected JSDoc line to have no prefix. + +/** + *@param {Number} foo + */function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never"] +// Message: Expected JSDoc line to have no prefix. +```` + +The following patterns are not considered problems: + +````js +/** + * Desc + * + * @param {Number} foo + * This is more comment. + */ +function quux (foo) { + +} + +/** + * Desc + * + * @param {{ + * foo: Bar, + * bar: Baz + * }} foo + * + */ +function quux (foo) { + +} + +/* <- JSDoc must start with 2 stars. + So this is unchecked. + */ +function quux (foo) {} + +/** @param {Number} foo */ +function quux (foo) { + // with spaces +} + + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "always",{"tags":{"any":["param"]}}] + + +/** + * @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never",{"tags":{"always":["param"]}}] + + +/** + * @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "always",{"tags":{"never":["someOtherTag"]}}] + + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "always",{"tags":{"never":["param"]}}] + + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never",{"tags":{"always":["someOtherTag"]}}] + + +/** + * Desc + * + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "never",{"tags":{"any":["*description"]}}] + + +/** + * Desc + + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "always",{"tags":{"any":["*description"]}}] + + +/** + @param {Number} foo + */ +function quux (foo) { + // with spaces +} +// "jsdoc/require-asterisk-prefix": ["error"|"warn", "any",{"tags":{"always":["someOtherTag"]}}] +```` + + ### require-description-complete-sentence @@ -8387,10 +8662,10 @@ Requires that block description, explicit `@description`, and * Periods after items within the `abbreviations` option array are not treated as sentence endings. - + #### Options - + ##### tags If you want additional tags to be checked for their descriptions, you may @@ -8414,14 +8689,14 @@ its "description" (e.g., for `@returns {someType} some description`, the description is `some description` while for `@some-tag xyz`, the description is `xyz`). - + ##### abbreviations You can provide an `abbreviations` options array to avoid such strings of text being treated as sentence endings when followed by dots. The `.` is not necessary at the end of the array items. - + ##### newlineBeforeCapsAssumesBadSentenceEnd When `false` (the new default), we will not assume capital letters after @@ -9092,7 +9367,7 @@ Requires that all functions have a description. is `"tag"`) must have a non-empty description that explains the purpose of the method. - + #### Options An options object may have any of the following properties: @@ -9607,12 +9882,12 @@ Requires that all functions have examples. * Every example tag must have a non-empty description that explains the method's usage. - + #### Options This rule has an object option. - + ##### exemptedBy Array of tags (e.g., `['type']`) whose presence on the document @@ -9621,13 +9896,13 @@ block avoids the need for an `@example`. Defaults to an array with so be sure to add back `inheritdoc` if you wish its presence to cause exemption of the rule. - + ##### exemptNoArguments Boolean to indicate that no-argument functions should not be reported for missing `@example` declarations. - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -9639,18 +9914,18 @@ want the rule to apply to any jsdoc block throughout your files. See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. - + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. - + ##### checkGetters A value indicating whether getters should be checked. Defaults to `false`. - + ##### checkSetters A value indicating whether setters should be checked. Defaults to `false`. @@ -9942,10 +10217,10 @@ Checks that: as being when the overview tag is not preceded by anything other than a comment. - + #### Options - + ##### tags The keys of this object are tag names, and the values are configuration @@ -10228,7 +10503,7 @@ function quux () { Requires (or disallows) a hyphen before the `@param` description. - + #### Options This rule takes one optional string argument and an optional options object. @@ -10459,12 +10734,12 @@ function main(argv) { Checks for presence of jsdoc comments, on class declarations as well as functions. - + #### Options Accepts one optional options object with the following optional keys. - + ##### publicOnly This option will insist that missing jsdoc blocks are only reported for @@ -10480,7 +10755,7 @@ otherwise noted): - `cjs` - CommonJS exports are checked for JSDoc comments (Defaults to `true`) - `window` - Window global exports are checked for JSDoc comments - + ##### require An object with the following optional boolean keys which all default to @@ -10493,7 +10768,7 @@ An object with the following optional boolean keys which all default to - `FunctionExpression` - `MethodDefinition` - + ##### contexts Set this to an array of strings or objects representing the additional AST @@ -10509,7 +10784,7 @@ if you are specifying a more precise form in `contexts` (e.g., `MethodDefinition See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. - + ##### exemptEmptyConstructors Default: true @@ -10518,7 +10793,7 @@ When `true`, the rule will not report missing jsdoc blocks above constructors with no parameters or return values (this is enabled by default as the class name or description should be seen as sufficient to convey intent). - + ##### exemptEmptyFunctions Default: false. @@ -10527,14 +10802,14 @@ When `true`, the rule will not report missing jsdoc blocks above functions/methods with no parameters or return values (intended where function/method names are sufficient for themselves as documentation). - + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. When `true`, `exemptEmptyConstructors` may still avoid reporting when no parameters or return values are found. - + ##### checkGetters A value indicating whether getters should be checked. Besides setting as a @@ -10543,7 +10818,7 @@ getters should be checked but only when there is no setter. This may be useful if one only wishes documentation on one of the two accessors. Defaults to `false`. - + ##### checkSetters A value indicating whether setters should be checked. Besides setting as a @@ -10552,7 +10827,7 @@ setters should be checked but only when there is no getter. This may be useful if one only wishes documentation on one of the two accessors. Defaults to `false`. - + ##### enableFixer A boolean on whether to enable the fixer (which adds an empty jsdoc block). @@ -12081,10 +12356,10 @@ export class User { Requires that each `@param` tag has a `description` value. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -12205,10 +12480,10 @@ Requires that all function parameters have names. > > [JSDoc](https://jsdoc.app/tags-param.html#overview) - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -12341,10 +12616,10 @@ function example(cb) { Requires that each `@param` tag has a `type` value. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -12642,30 +12917,30 @@ other properties, so in looking at the docs alone without looking at the function signature, it may appear that there is an actual property named `extra`. - + #### Options An options object accepts the following optional properties: - + ##### enableFixer Whether to enable the fixer. Defaults to `true`. - + ##### enableRootFixer Whether to enable the auto-adding of incrementing roots (see the "Fixer" section). Defaults to `true`. Has no effect if `enableFixer` is set to `false`. - + ##### enableRestElementFixer Whether to enable the rest element fixer (see "Rest Element (`RestElement`) insertions"). Defaults to `true`. - + ##### checkRestProperty If set to `true`, will report (and add fixer insertions) for missing rest @@ -12719,13 +12994,13 @@ function quux ({num, ...extra}) { } ``` - + ##### autoIncrementBase Numeric to indicate the number at which to begin auto-incrementing roots. Defaults to `0`. - + ##### unnamedRootBase An array of root names to use in the fixer when roots are missing. Defaults @@ -12751,7 +13026,7 @@ function quux ({foo}, [bar], {baz}) { */ ``` - + ##### exemptedBy Array of tags (e.g., `['type']`) whose presence on the document block @@ -12760,7 +13035,7 @@ avoids the need for a `@param`. Defaults to an array with so be sure to add back `inheritdoc` if you wish its presence to cause exemption of the rule. - + ##### checkTypesPattern When one specifies a type, unless it is of a generic type, like `object` @@ -12795,7 +13070,7 @@ You could set this regular expression to a more expansive list, or you could restrict it such that even types matching those strings would not need destructuring. - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -12807,28 +13082,28 @@ which are checked. See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. - + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. - + ##### checkGetters A value indicating whether getters should be checked. Defaults to `false`. - + ##### checkSetters A value indicating whether setters should be checked. Defaults to `false`. - + ##### checkDestructured Whether to require destructured properties. Defaults to `true`. - + ##### checkDestructuredRoots Whether to check the existence of a corresponding `@param` for root objects @@ -12841,7 +13116,7 @@ implied to be `false` (i.e., the inside of the roots will not be checked either, e.g., it will also not complain if `a` or `b` do not have their own documentation). Defaults to `true`. - + ##### useDefaultObjectProperties Set to `true` if you wish to expect documentation of properties on objects @@ -14444,7 +14719,7 @@ is set to `false` no non-`undefined` returned or resolved value is found. Will also report if multiple `@returns` tags are present. - + #### Options - `exemptAsync` - By default, functions which return a `Promise` that are not @@ -14971,10 +15246,10 @@ Requires that the `@returns` tag has a `description` value. The error will not be reported if the return value is `void` or `undefined` or if it is `Promise` or `Promise`. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -15127,10 +15402,10 @@ function quux () { Requires that `@returns` tag has `type` value. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -15250,7 +15525,7 @@ Requires that returns are documented. Will also report if multiple `@returns` tags are present. - + #### Options - `checkConstructors` - A value indicating whether `constructor`s should @@ -16271,7 +16546,7 @@ async function foo() { Requires that throw statements are documented. - + #### Options - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the @@ -16547,7 +16822,7 @@ Will also report if multiple `@yields` tags are present. See the `next`, `forceRequireNext`, and `nextWithGeneratorTag` options for an option to expect a non-standard `@next` tag. - + #### Options - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the @@ -17357,7 +17632,7 @@ function bodies. Will also report if multiple `@yields` tags are present. - + #### Options - `checkGeneratorsOnly` - Avoids checking the function body and merely insists @@ -17910,7 +18185,7 @@ for valid types (based on the tag's `type` value), and either portion checked for presence (based on `false` `name` or `type` values or their `required` value). See the setting for more details. - + #### Options - `allowEmptyNamepaths` (default: true) - Set to `false` to bulk disallow diff --git a/src/index.js b/src/index.js index eee20b174..370ca16b5 100644 --- a/src/index.js +++ b/src/index.js @@ -19,6 +19,7 @@ import noMissingSyntax from './rules/noMissingSyntax'; import noRestrictedSyntax from './rules/noRestrictedSyntax'; import noTypes from './rules/noTypes'; import noUndefinedTypes from './rules/noUndefinedTypes'; +import requireAsteriskPrefix from './rules/requireAsteriskPrefix'; import requireDescription from './rules/requireDescription'; import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence'; import requireExample from './rules/requireExample'; @@ -68,6 +69,7 @@ export default { 'jsdoc/no-restricted-syntax': 'off', 'jsdoc/no-types': 'off', 'jsdoc/no-undefined-types': 'warn', + 'jsdoc/require-asterisk-prefix': 'off', 'jsdoc/require-description': 'off', 'jsdoc/require-description-complete-sentence': 'off', 'jsdoc/require-example': 'off', @@ -115,6 +117,7 @@ export default { 'no-restricted-syntax': noRestrictedSyntax, 'no-types': noTypes, 'no-undefined-types': noUndefinedTypes, + 'require-asterisk-prefix': requireAsteriskPrefix, 'require-description': requireDescription, 'require-description-complete-sentence': requireDescriptionCompleteSentence, 'require-example': requireExample, diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js index a460156d5..0c03239c3 100644 --- a/src/iterateJsdoc.js +++ b/src/iterateJsdoc.js @@ -141,7 +141,7 @@ const getUtils = ( utils.getDescription = () => { const descriptions = []; - let lastDescriptionLine; + let lastDescriptionLine = 0; jsdoc.source.some(({tokens: {description, tag, end}}, idx) => { if (idx && (tag || end)) { lastDescriptionLine = idx - 1; diff --git a/src/rules/requireAsteriskPrefix.js b/src/rules/requireAsteriskPrefix.js new file mode 100644 index 000000000..a99675801 --- /dev/null +++ b/src/rules/requireAsteriskPrefix.js @@ -0,0 +1,149 @@ +import iterateJsdoc from '../iterateJsdoc'; + +export default iterateJsdoc(({ + context, + jsdoc, + utils, + indent, +}) => { + const [defaultRequireValue = 'always', { + tags: tagMap = {}, + } = {}] = context.options; + + const {source} = jsdoc; + + const always = defaultRequireValue === 'always'; + const never = defaultRequireValue === 'never'; + + let currentTag; + source.some(({number, tokens}) => { + const {delimiter, tag, end, description} = tokens; + + const neverFix = () => { + tokens.delimiter = ''; + tokens.postDelimiter = ''; + }; + const checkNever = (checkValue) => { + if (delimiter && delimiter !== '/**' && ( + never && !tagMap.always?.includes(checkValue) || + tagMap.never?.includes(checkValue) + )) { + utils.reportJSDoc('Expected JSDoc line to have no prefix.', { + column: 0, + line: number, + }, neverFix); + + return true; + } + + return false; + }; + + const alwaysFix = () => { + if (!tokens.start) { + tokens.start = indent + ' '; + } + tokens.delimiter = '*'; + tokens.postDelimiter = tag || description ? ' ' : ''; + }; + const checkAlways = (checkValue) => { + if ( + !delimiter && ( + always && !tagMap.never?.includes(checkValue) || + tagMap.always?.includes(checkValue) + ) + ) { + utils.reportJSDoc('Expected JSDoc line to have the prefix.', { + column: 0, + line: number, + }, alwaysFix); + + return true; + } + + return false; + }; + + if (tag) { + // Remove at sign + currentTag = tag.slice(1); + } + + if ( + // If this is the end but has a tag, the delimiter will also be + // populated and will be safely ignored later + end && !tag + ) { + return false; + } + + if (!currentTag) { + if (tagMap.any?.includes('*description')) { + return false; + } + if (checkNever('*description')) { + return true; + } + if (checkAlways('*description')) { + return true; + } + + return false; + } + + if (tagMap.any?.includes(currentTag)) { + return false; + } + + if (checkNever(currentTag)) { + return true; + } + + if (checkAlways(currentTag)) { + return true; + } + + return false; + }); +}, { + iterateAllJsdocs: true, + meta: { + fixable: 'code', + schema: [ + { + enum: ['always', 'never', 'any'], + type: 'string', + }, + { + additionalProperties: false, + properties: { + tags: { + properties: { + always: { + items: { + type: 'string', + }, + type: 'array', + }, + any: { + items: { + type: 'string', + }, + type: 'array', + }, + never: { + items: { + type: 'string', + }, + type: 'array', + }, + }, + type: 'object', + }, + }, + type: 'object', + }, + ], + type: 'layout', + }, +}); diff --git a/test/rules/assertions/requireAsteriskPrefix.js b/test/rules/assertions/requireAsteriskPrefix.js new file mode 100644 index 000000000..4ef9989d7 --- /dev/null +++ b/test/rules/assertions/requireAsteriskPrefix.js @@ -0,0 +1,523 @@ +export default { + invalid: [ + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have the prefix.', + }, + ], + output: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have the prefix.', + }, + ], + options: [ + 'any', { + tags: { + always: ['param'], + }, + }, + ], + output: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + * Desc + + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 5, + message: 'Expected JSDoc line to have the prefix.', + }, + ], + output: ` + + /** + * Desc + * + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + * + Desc + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 5, + message: 'Expected JSDoc line to have the prefix.', + }, + ], + output: ` + + /** + * + * Desc + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + * Desc + * + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have no prefix.', + }, + ], + options: ['never'], + output: ` + + /** + Desc + * + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have the prefix.', + }, + ], + options: ['always', { + tags: { + any: ['someOtherTag'], + }, + }], + output: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have no prefix.', + }, + ], + options: ['never', { + tags: { + always: ['someOtherTag'], + }, + }], + output: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have no prefix.', + }, + ], + options: ['always', { + tags: { + never: ['param'], + }, + }], + output: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have the prefix.', + }, + ], + options: ['never', { + tags: { + always: ['param'], + }, + }], + output: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + /** + @param {Number} foo + */function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 3, + message: 'Expected JSDoc line to have the prefix.', + }, + ], + output: ` + /** + * @param {Number} foo + */function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 4, + message: 'Expected JSDoc line to have no prefix.', + }, + ], + options: ['never'], + output: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + /** + *@param {Number} foo + */function quux (foo) { + // with spaces + } + `, + errors: [ + { + line: 3, + message: 'Expected JSDoc line to have no prefix.', + }, + ], + options: ['never'], + output: ` + /** + @param {Number} foo + */function quux (foo) { + // with spaces + } + `, + }, + ], + valid: [ + { + code: ` + /** + * Desc + * + * @param {Number} foo + * This is more comment. + */ + function quux (foo) { + + } + `, + }, + { + code: ` + /** + * Desc + * + * @param {{ + * foo: Bar, + * bar: Baz + * }} foo + * + */ + function quux (foo) { + + } + `, + }, + { + code: ` + /* <- JSDoc must start with 2 stars. + So this is unchecked. + */ + function quux (foo) {} + `, + }, + { + code: ` + /** @param {Number} foo */ + function quux (foo) { + // with spaces + } + `, + }, + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + options: ['always', { + tags: { + any: ['param'], + }, + }], + }, + { + code: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + options: ['never', { + tags: { + always: ['param'], + }, + }], + }, + { + code: ` + + /** + * @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + options: ['always', { + tags: { + never: ['someOtherTag'], + }, + }], + }, + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + options: ['always', { + tags: { + never: ['param'], + }, + }], + }, + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + options: ['never', { + tags: { + always: ['someOtherTag'], + }, + }], + }, + { + code: ` + + /** + * Desc + * + */ + function quux (foo) { + // with spaces + } + `, + options: ['never', { + tags: { + any: ['*description'], + }, + }], + }, + { + code: ` + + /** + * Desc + + */ + function quux (foo) { + // with spaces + } + `, + options: ['always', { + tags: { + any: ['*description'], + }, + }], + }, + { + code: ` + + /** + @param {Number} foo + */ + function quux (foo) { + // with spaces + } + `, + options: [ + 'any', { + tags: { + always: ['someOtherTag'], + }, + }, + ], + }, + ], +}; diff --git a/test/rules/index.js b/test/rules/index.js index 0c7c3f66d..7852b0687 100644 --- a/test/rules/index.js +++ b/test/rules/index.js @@ -28,6 +28,7 @@ const ruleTester = new RuleTester(); 'no-restricted-syntax', 'no-types', 'no-undefined-types', + 'require-asterisk-prefix', 'require-description', 'require-description-complete-sentence', 'require-example',