Skip to content

Commit

Permalink
feat(informative-docs): add excludedTags; fixes #1153
Browse files Browse the repository at this point in the history
Also:
- fix(`informative-docs`): proper `aliases` schema
- test(`informative-docs`): check `uselessWords`
- test(`require-jsdoc`): example for Vue components
  • Loading branch information
brettz9 committed Sep 10, 2023
1 parent 85a21bf commit 6f1b50b
Show file tree
Hide file tree
Showing 6 changed files with 143 additions and 7 deletions.
2 changes: 1 addition & 1 deletion .README/rules/informative-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ The default `uselessWords` option is:
|Tags|any|
|Recommended|false|
|Settings||
|Options|`aliases`, `uselessWords`|
|Options|`aliases`, `excludedTags`, `uselessWords`|

## Failing examples

Expand Down
22 changes: 19 additions & 3 deletions docs/rules/informative-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ The default `uselessWords` option is:
|Tags|any|
|Recommended|false|
|Settings||
|Options|`aliases`, `uselessWords`|
|Options|`aliases`, `excludedTags`, `uselessWords`|

<a name="user-content-informative-docs-failing-examples"></a>
<a name="informative-docs-failing-examples"></a>
Expand Down Expand Up @@ -249,6 +249,11 @@ function takesOne(param) {}
*/
function takesOne(param) {}
// Message: This description only repeats the name it describes.

/** A smiley/winkey. */
let emoji;
// "jsdoc/informative-docs": ["error"|"warn", {"aliases":{"emoji":["smiley","winkey"]}}]
// Message: This description only repeats the name it describes.
````


Expand Down Expand Up @@ -391,10 +396,21 @@ function takesOne(param) {}
function takesOne(param) {}

/**
* @class
* @class
*
* @param {number} value - Some useful text
*/
*/
function MyAmazingThing(value) {}

/**
* My option.
* @default {}
*/
// "jsdoc/informative-docs": ["error"|"warn", {"excludedTags":["default"]}]

/**
* The
*/
// "jsdoc/informative-docs": ["error"|"warn", {"uselessWords":["an"]}]
````

22 changes: 22 additions & 0 deletions docs/rules/require-jsdoc.md
Original file line number Diff line number Diff line change
Expand Up @@ -1857,5 +1857,27 @@ export default class Test {
}
}
// "jsdoc/require-jsdoc": ["error"|"warn", {"publicOnly":true,"require":{"ArrowFunctionExpression":false,"ClassDeclaration":false,"ClassExpression":false,"FunctionDeclaration":false,"FunctionExpression":false,"MethodDefinition":true}}]

export default {
created() {
this.getData();
},

beforeUpdate() {},

watch: {
someValue(val) {}
},

computed: {
loaded() {},
selection() {}
},

methods: {
getData(id) {}
}
};
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(created|beforeUpdate)$/] > FunctionExpression","ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(watch|computed|methods)$/] > ObjectExpression > Property > FunctionExpression"]}]
````

17 changes: 16 additions & 1 deletion src/rules/informativeDocs.js
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,9 @@ export default iterateJsdoc(({
report,
utils,
}) => {
const {
const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */ {
aliases = defaultAliases,
excludedTags = [],
uselessWords = defaultUselessWords,
} = context.options[0] || {};
const nodeNames = getNamesFromNode(node);
Expand All @@ -119,6 +120,10 @@ export default iterateJsdoc(({
let descriptionReported = false;

for (const tag of jsdoc.tags) {
if (excludedTags.includes(tag.tag)) {
continue;
}

if (descriptionIsRedundant(tag.description, tag.name)) {
utils.reportJSDoc(
'This tag description only repeats the name it describes.',
Expand Down Expand Up @@ -147,6 +152,16 @@ export default iterateJsdoc(({
additionalProperties: false,
properties: {
aliases: {
patternProperties: {
'.*': {
items: {
type: 'string',
},
type: 'array',
},
},
},
excludedTags: {
items: {
type: 'string',
},
Expand Down
54 changes: 52 additions & 2 deletions test/rules/assertions/informativeDocs.js
Original file line number Diff line number Diff line change
Expand Up @@ -476,6 +476,27 @@ export default {
},
],
},
{
code: `
/** A smiley/winkey. */
let emoji;
`,
errors: [
{
line: 2,
message: 'This description only repeats the name it describes.',
},
],
options: [
{
aliases: {
emoji: [
'smiley', 'winkey',
],
},
},
],
},
],
valid: [
{
Expand Down Expand Up @@ -752,12 +773,41 @@ export default {
{
code: `
/**
* @class
* @class
*
* @param {number} value - Some useful text
*/
*/
function MyAmazingThing(value) {}
`,
},
{
code: `
/**
* My option.
* @default {}
*/
`,
options: [
{
excludedTags: [
'default',
],
},
],
},
{
code: `
/**
* The
*/
`,
options: [
{
uselessWords: [
'an',
],
},
],
},
],
};
33 changes: 33 additions & 0 deletions test/rules/assertions/requireJsdoc.js
Original file line number Diff line number Diff line change
Expand Up @@ -6202,5 +6202,38 @@ function quux (foo) {
sourceType: 'module',
},
},
{
code: `
export default {
created() {
this.getData();
},
beforeUpdate() {},
watch: {
someValue(val) {}
},
computed: {
loaded() {},
selection() {}
},
methods: {
getData(id) {}
}
};
`,
options: [
{
contexts: [
'ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(created|beforeUpdate)$/] > FunctionExpression',
'ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(watch|computed|methods)$/] > ObjectExpression > Property > FunctionExpression',
],
},
],
parser: require.resolve('@typescript-eslint/parser'),
},
],
};

0 comments on commit 6f1b50b

Please sign in to comment.