Skip to content

Commit e5f2a23

Browse files
brettz9brettz9
committed
feat(require-property*): add rules for ensuring property tags have a name, type, and/or description (in any context); fixes #409
BREAKING CHANGE: Adds rules to `recommended`
1 parent 68bf6cd commit e5f2a23

13 files changed

+558
-0
lines changed

‎.README/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,9 @@ only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
353353
{"gitdown": "include", "file": "./rules/require-param-type.md"}
354354
{"gitdown": "include", "file": "./rules/require-param.md"}
355355
{"gitdown": "include", "file": "./rules/require-property.md"}
356+
{"gitdown": "include", "file": "./rules/require-property-description.md"}
357+
{"gitdown": "include", "file": "./rules/require-property-name.md"}
358+
{"gitdown": "include", "file": "./rules/require-property-type.md"}
356359
{"gitdown": "include", "file": "./rules/require-returns-check.md"}
357360
{"gitdown": "include", "file": "./rules/require-returns-description.md"}
358361
{"gitdown": "include", "file": "./rules/require-returns-type.md"}

‎.README/rules/require-property-description.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `require-property-description`
2+
3+
Requires that each `@property` tag has a `description` value.
4+
5+
|||
6+
|---|---|
7+
|Context|everywhere|
8+
|Tags|N/A|
9+
10+
<!-- assertions requirePropertyDescription -->

‎.README/rules/require-property-name.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `require-property-name`
2+
3+
Requires that all function `@property` tags have names.
4+
5+
|||
6+
|---|---|
7+
|Context|everywhere|
8+
|Tags|N/A|
9+
10+
<!-- assertions requirePropertyName -->

‎.README/rules/require-property-type.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `require-property-type`
2+
3+
Requires that each `@property` tag has a `type` value.
4+
5+
|||
6+
|---|---|
7+
|Context|everywhere|
8+
|Tags|N/A|
9+
10+
<!-- assertions requirePropertyType -->

‎README.md

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ JSDoc linting rules for ESLint.
4545
* [`require-param-type`](#eslint-plugin-jsdoc-rules-require-param-type)
4646
* [`require-param`](#eslint-plugin-jsdoc-rules-require-param)
4747
* [`require-property`](#eslint-plugin-jsdoc-rules-require-property)
48+
* [`require-property-description`](#eslint-plugin-jsdoc-rules-require-property-description)
49+
* [`require-property-name`](#eslint-plugin-jsdoc-rules-require-property-name)
50+
* [`require-property-type`](#eslint-plugin-jsdoc-rules-require-property-type)
4851
* [`require-returns-check`](#eslint-plugin-jsdoc-rules-require-returns-check)
4952
* [`require-returns-description`](#eslint-plugin-jsdoc-rules-require-returns-description)
5053
* [`require-returns-type`](#eslint-plugin-jsdoc-rules-require-returns-type)
@@ -8593,6 +8596,180 @@ function quux () {
85938596
````
85948597

85958598

8599+
<a name="eslint-plugin-jsdoc-rules-require-property-description"></a>
8600+
### <code>require-property-description</code>
8601+
8602+
Requires that each `@property` tag has a `description` value.
8603+
8604+
|||
8605+
|---|---|
8606+
|Context|everywhere|
8607+
|Tags|N/A|
8608+
8609+
The following patterns are considered problems:
8610+
8611+
````js
8612+
/**
8613+
* @typedef {SomeType} SomeTypedef
8614+
* @property foo
8615+
*/
8616+
// Message: Missing JSDoc @property "foo" description.
8617+
8618+
/**
8619+
* @typedef {SomeType} SomeTypedef
8620+
* @prop foo
8621+
*/
8622+
// Settings: {"jsdoc":{"tagNamePreference":{"property":"prop"}}}
8623+
// Message: Missing JSDoc @prop "foo" description.
8624+
8625+
/**
8626+
* @typedef {SomeType} SomeTypedef
8627+
* @property foo
8628+
*/
8629+
// Settings: {"jsdoc":{"tagNamePreference":{"property":false}}}
8630+
// Message: Unexpected tag `@property`
8631+
````
8632+
8633+
The following patterns are not considered problems:
8634+
8635+
````js
8636+
/**
8637+
* @typedef {SomeType} SomeTypedef
8638+
*/
8639+
8640+
/**
8641+
* @typedef {SomeType} SomeTypedef
8642+
* @property foo Foo.
8643+
*/
8644+
8645+
/**
8646+
* @namespace {SomeType} SomeName
8647+
* @property foo Foo.
8648+
*/
8649+
8650+
/**
8651+
* @class
8652+
* @property foo Foo.
8653+
*/
8654+
````
8655+
8656+
8657+
<a name="eslint-plugin-jsdoc-rules-require-property-name"></a>
8658+
### <code>require-property-name</code>
8659+
8660+
Requires that all function `@property` tags have names.
8661+
8662+
|||
8663+
|---|---|
8664+
|Context|everywhere|
8665+
|Tags|N/A|
8666+
8667+
The following patterns are considered problems:
8668+
8669+
````js
8670+
/**
8671+
* @typedef {SomeType} SomeTypedef
8672+
* @property
8673+
*/
8674+
// Message: There must be an identifier after @property type.
8675+
8676+
/**
8677+
* @typedef {SomeType} SomeTypedef
8678+
* @property {string}
8679+
*/
8680+
// Message: There must be an identifier after @property tag.
8681+
8682+
/**
8683+
* @typedef {SomeType} SomeTypedef
8684+
* @property foo
8685+
*/
8686+
// Settings: {"jsdoc":{"tagNamePreference":{"property":false}}}
8687+
// Message: Unexpected tag `@property`
8688+
````
8689+
8690+
The following patterns are not considered problems:
8691+
8692+
````js
8693+
/**
8694+
* @typedef {SomeType} SomeTypedef
8695+
* @property foo
8696+
*/
8697+
8698+
/**
8699+
* @typedef {SomeType} SomeTypedef
8700+
* @property {string} foo
8701+
*/
8702+
8703+
/**
8704+
* @namespace {SomeType} SomeName
8705+
* @property {string} foo
8706+
*/
8707+
8708+
/**
8709+
* @class
8710+
* @property {string} foo
8711+
*/
8712+
````
8713+
8714+
8715+
<a name="eslint-plugin-jsdoc-rules-require-property-type"></a>
8716+
### <code>require-property-type</code>
8717+
8718+
Requires that each `@property` tag has a `type` value.
8719+
8720+
|||
8721+
|---|---|
8722+
|Context|everywhere|
8723+
|Tags|N/A|
8724+
8725+
The following patterns are considered problems:
8726+
8727+
````js
8728+
/**
8729+
* @typedef {SomeType} SomeTypedef
8730+
* @property foo
8731+
*/
8732+
// Message: Missing JSDoc @property "foo" type.
8733+
8734+
/**
8735+
* @typedef {SomeType} SomeTypedef
8736+
* @prop foo
8737+
*/
8738+
// Settings: {"jsdoc":{"tagNamePreference":{"property":"prop"}}}
8739+
// Message: Missing JSDoc @prop "foo" type.
8740+
8741+
/**
8742+
* @typedef {SomeType} SomeTypedef
8743+
* @property foo
8744+
*/
8745+
// Settings: {"jsdoc":{"tagNamePreference":{"property":false}}}
8746+
// Message: Unexpected tag `@property`
8747+
````
8748+
8749+
The following patterns are not considered problems:
8750+
8751+
````js
8752+
/**
8753+
* @typedef {SomeType} SomeTypedef
8754+
*/
8755+
8756+
/**
8757+
* @typedef {SomeType} SomeTypedef
8758+
* @property {number} foo
8759+
*/
8760+
8761+
/**
8762+
* @namespace {SomeType} SomeName
8763+
* @property {number} foo
8764+
*/
8765+
8766+
/**
8767+
* @class
8768+
* @property {number} foo
8769+
*/
8770+
````
8771+
8772+
85968773
<a name="eslint-plugin-jsdoc-rules-require-returns-check"></a>
85978774
### <code>require-returns-check</code>
85988775

‎src/index.js

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@ import requireParam from './rules/requireParam';
2424
import requireParamDescription from './rules/requireParamDescription';
2525
import requireParamType from './rules/requireParamType';
2626
import requireProperty from './rules/requireProperty';
27+
import requirePropertyDescription from './rules/requirePropertyDescription';
28+
import requirePropertyName from './rules/requirePropertyName';
29+
import requirePropertyType from './rules/requirePropertyType';
2730
import requireReturns from './rules/requireReturns';
2831
import requireReturnsCheck from './rules/requireReturnsCheck';
2932
import requireReturnsDescription from './rules/requireReturnsDescription';
@@ -62,6 +65,9 @@ export default {
6265
'jsdoc/require-param-name': 'warn',
6366
'jsdoc/require-param-type': 'warn',
6467
'jsdoc/require-property': 'warn',
68+
'jsdoc/require-property-description': 'warn',
69+
'jsdoc/require-property-name': 'warn',
70+
'jsdoc/require-property-type': 'warn',
6571
'jsdoc/require-returns': 'warn',
6672
'jsdoc/require-returns-check': 'warn',
6773
'jsdoc/require-returns-description': 'warn',
@@ -97,6 +103,9 @@ export default {
97103
'require-param-name': requireParamName,
98104
'require-param-type': requireParamType,
99105
'require-property': requireProperty,
106+
'require-property-description': requirePropertyDescription,
107+
'require-property-name': requirePropertyName,
108+
'require-property-type': requirePropertyType,
100109
'require-returns': requireReturns,
101110
'require-returns-check': requireReturnsCheck,
102111
'require-returns-description': requireReturnsDescription,

‎src/rules/requirePropertyDescription.js

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import iterateJsdoc from '../iterateJsdoc';
2+
3+
export default iterateJsdoc(({
4+
report,
5+
utils,
6+
}) => {
7+
utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
8+
if (!jsdoc.description) {
9+
report(
10+
`Missing JSDoc @${targetTagName} "${jsdoc.name}" description.`,
11+
null,
12+
jsdoc,
13+
);
14+
}
15+
});
16+
}, {
17+
iterateAllJsdocs: true,
18+
meta: {
19+
type: 'suggestion',
20+
},
21+
});

‎src/rules/requirePropertyName.js

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import iterateJsdoc from '../iterateJsdoc';
2+
3+
export default iterateJsdoc(({
4+
report,
5+
utils,
6+
}) => {
7+
utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
8+
if (jsdoc.tag && jsdoc.name === '') {
9+
report(
10+
`There must be an identifier after @${targetTagName} ${jsdoc.type === '' ? 'type' : 'tag'}.`,
11+
null,
12+
jsdoc,
13+
);
14+
}
15+
});
16+
}, {
17+
iterateAllJsdocs: true,
18+
meta: {
19+
type: 'suggestion',
20+
},
21+
});

‎src/rules/requirePropertyType.js

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import iterateJsdoc from '../iterateJsdoc';
2+
3+
export default iterateJsdoc(({
4+
report,
5+
utils,
6+
}) => {
7+
utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
8+
if (!jsdoc.type) {
9+
report(
10+
`Missing JSDoc @${targetTagName} "${jsdoc.name}" type.`,
11+
null,
12+
jsdoc,
13+
);
14+
}
15+
});
16+
}, {
17+
iterateAllJsdocs: true,
18+
meta: {
19+
type: 'suggestion',
20+
},
21+
});

0 commit comments

Comments
 (0)