Skip to content

Commit f6e467e

Browse files
brettz9brettz9
committed
feat(require-file-overview): allow user to specify whether checking for tag, duplicates, or preceding non-comments, and for which tags
1 parent c4079b8 commit f6e467e

File tree

5 files changed

+576
-23
lines changed

5 files changed

+576
-23
lines changed

‎.README/rules/require-file-overview.md

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,68 @@ Checks that:
1010
as being when the overview tag is not preceded by anything other than
1111
a comment.
1212

13+
#### Options
14+
15+
##### `tags`
16+
17+
The keys of this object are tag names, and the values are configuration
18+
objects indicating what will be checked for these whole-file tags.
19+
20+
Each configuration object has the following boolean keys (which default
21+
to `false` when this option is supplied): `mustExist`, `preventDuplicates`,
22+
`initialCommentsOnly`. These correspond to the three items above.
23+
24+
When no `tags` is present, the default is:
25+
26+
```json
27+
{
28+
"file": {
29+
"initialCommentsOnly": true,
30+
"mustExist": true,
31+
"preventDuplicates": true,
32+
}
33+
}
34+
```
35+
36+
You can add additional tag names and/or override `file` if you supply this
37+
option, e.g., in place of or in addition to `file`, giving other potential
38+
file global tags like `@license`, `@copyright`, `@author`, `@module` or
39+
`@exports`, optionally restricting them to a single use or preventing them
40+
from being preceded by anything besides comments.
41+
42+
For example:
43+
44+
```js
45+
{
46+
"license": {
47+
"mustExist": true,
48+
"preventDuplicates": true,
49+
}
50+
}
51+
```
52+
53+
This would require one and only one `@license` in the file, though because
54+
`initialCommentsOnly` is absent and defaults to `false`, the `@license`
55+
can be anywhere.
56+
57+
In the case of `@license`, you can use this rule along with the
58+
`check-values` rule (with its `allowedLicenses` or `licensePattern` options),
59+
to enforce a license whitelist be present on every JS file.
60+
61+
Note that if you choose to use `preventDuplicates` with `license`, you still
62+
have a way to allow multiple licenses for the whole page by using the SPDX
63+
"AND" expression, e.g., `@license (MIT AND GPL-3.0)`.
64+
65+
Note that the tag names are the main jsdoc tag name, so you should use `file`
66+
in this configuration object regardless of whether you have configured
67+
`fileoverview` instead of `file` on `tagNamePreference` (i.e., `fileoverview`
68+
will be checked, but you must use `file` on the configuration object).
69+
1370
|||
1471
|---|---|
1572
|Context|Everywhere|
16-
|Tags|`file`|
73+
|Tags|`file`; others when `tags` set|
1774
|Aliases|`fileoverview`, `overview`|
75+
|Options|`tags`|
1876

1977
<!-- assertions requireFileOverview -->

‎README.md

Lines changed: 173 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6716,18 +6716,90 @@ Checks that:
67166716
as being when the overview tag is not preceded by anything other than
67176717
a comment.
67186718
6719+
<a name="eslint-plugin-jsdoc-rules-require-file-overview-options-17"></a>
6720+
#### Options
6721+
6722+
<a name="eslint-plugin-jsdoc-rules-require-file-overview-options-17-tags-3"></a>
6723+
##### <code>tags</code>
6724+
6725+
The keys of this object are tag names, and the values are configuration
6726+
objects indicating what will be checked for these whole-file tags.
6727+
6728+
Each configuration object has the following boolean keys (which default
6729+
to `false` when this option is supplied): `mustExist`, `preventDuplicates`,
6730+
`initialCommentsOnly`. These correspond to the three items above.
6731+
6732+
When no `tags` is present, the default is:
6733+
6734+
```json
6735+
{
6736+
"file": {
6737+
"initialCommentsOnly": true,
6738+
"mustExist": true,
6739+
"preventDuplicates": true,
6740+
}
6741+
}
6742+
```
6743+
6744+
You can add additional tag names and/or override `file` if you supply this
6745+
option, e.g., in place of or in addition to `file`, giving other potential
6746+
file global tags like `@license`, `@copyright`, `@author`, `@module` or
6747+
`@exports`, optionally restricting them to a single use or preventing them
6748+
from being preceded by anything besides comments.
6749+
6750+
For example:
6751+
6752+
```js
6753+
{
6754+
"license": {
6755+
"mustExist": true,
6756+
"preventDuplicates": true,
6757+
}
6758+
}
6759+
```
6760+
6761+
This would require one and only one `@license` in the file, though because
6762+
`initialCommentsOnly` is absent and defaults to `false`, the `@license`
6763+
can be anywhere.
6764+
6765+
In the case of `@license`, you can use this rule along with the
6766+
`check-values` rule (with its `allowedLicenses` or `licensePattern` options),
6767+
to enforce a license whitelist be present on every JS file.
6768+
6769+
Note that if you choose to use `preventDuplicates` with `license`, you still
6770+
have a way to allow multiple licenses for the whole page by using the SPDX
6771+
"AND" expression, e.g., `@license (MIT AND GPL-3.0)`.
6772+
6773+
Note that the tag names are the main jsdoc tag name, so you should use `file`
6774+
in this configuration object regardless of whether you have configured
6775+
`fileoverview` instead of `file` on `tagNamePreference` (i.e., `fileoverview`
6776+
will be checked, but you must use `file` on the configuration object).
6777+
67196778
|||
67206779
|---|---|
67216780
|Context|Everywhere|
6722-
|Tags|`file`|
6781+
|Tags|`file`; others when `tags` set|
67236782
|Aliases|`fileoverview`, `overview`|
6783+
|Options|`tags`|
67246784
67256785
The following patterns are considered problems:
67266786
67276787
````js
67286788
67296789
// Message: Missing @file
67306790
6791+
6792+
// Options: [{"tags":{"file":{"initialCommentsOnly":true,"mustExist":true,"preventDuplicates":true}}}]
6793+
// Message: Missing @file
6794+
6795+
6796+
// Options: [{"tags":{"file":{"mustExist":true}}}]
6797+
// Message: Missing @file
6798+
6799+
6800+
// Options: [{"tags":{"author":{"initialCommentsOnly":false,"mustExist":true,"preventDuplicates":false}}}]
6801+
// Message: Missing @author
6802+
67316803
/**
67326804
*
67336805
*/
@@ -6760,6 +6832,14 @@ function quux () {}
67606832
// Settings: {"jsdoc":{"tagNamePreference":{"file":false}}}
67616833
// Message: `settings.jsdoc.tagNamePreference` cannot block @file for the `require-file-overview` rule
67626834
6835+
/**
6836+
*
6837+
*/
6838+
function quux () {}
6839+
// Settings: {"jsdoc":{"tagNamePreference":{"file":false}}}
6840+
// Options: [{"tags":{"file":{"initialCommentsOnly":false,"mustExist":true,"preventDuplicates":false}}}]
6841+
// Message: `settings.jsdoc.tagNamePreference` cannot block @file for the `require-file-overview` rule
6842+
67636843
/**
67646844
*
67656845
*/
@@ -6793,12 +6873,48 @@ function bar (b) {}
67936873
*/
67946874
// Message: Duplicate @file
67956875
6876+
/**
6877+
* @copyright
6878+
*/
6879+
6880+
/**
6881+
* @copyright
6882+
*/
6883+
// Options: [{"tags":{"copyright":{"initialCommentsOnly":false,"mustExist":false,"preventDuplicates":true}}}]
6884+
// Message: Duplicate @copyright
6885+
67966886
function quux () {
67976887
}
67986888
/**
67996889
* @file
68006890
*/
68016891
// Message: @file should be at the beginning of the file
6892+
6893+
function quux () {
6894+
}
6895+
/**
6896+
* @license
6897+
*/
6898+
// Options: [{"tags":{"license":{"initialCommentsOnly":true,"mustExist":false,"preventDuplicates":false}}}]
6899+
// Message: @license should be at the beginning of the file
6900+
6901+
function quux () {
6902+
}
6903+
/**
6904+
* @license
6905+
*/
6906+
// Options: [{"tags":{"license":{"initialCommentsOnly":true}}}]
6907+
// Message: @license should be at the beginning of the file
6908+
6909+
/**
6910+
* @file
6911+
*/
6912+
6913+
/**
6914+
* @file
6915+
*/
6916+
// Options: [{"tags":{"file":{"initialCommentsOnly":true,"preventDuplicates":true}}}]
6917+
// Message: Duplicate @file
68026918
````
68036919
68046920
The following patterns are not considered problems:
@@ -6808,6 +6924,15 @@ The following patterns are not considered problems:
68086924
* @file
68096925
*/
68106926
6927+
/**
6928+
* @file
6929+
*/
6930+
6931+
/**
6932+
* @file
6933+
*/
6934+
// Options: [{"tags":{"license":{"initialCommentsOnly":true,"preventDuplicates":true}}}]
6935+
68116936
// Ok preceded by comment
68126937
/**
68136938
* @file
@@ -6836,6 +6961,38 @@ function quux () {
68366961
/**
68376962
*
68386963
*/
6964+
6965+
function quux () {
6966+
}
6967+
/**
6968+
*
6969+
*/
6970+
// Options: [{"tags":{"license":{"initialCommentsOnly":true,"mustExist":false,"preventDuplicates":false}}}]
6971+
6972+
function quux () {
6973+
}
6974+
/**
6975+
*
6976+
*/
6977+
// Options: [{"tags":{"license":{"initialCommentsOnly":false,"mustExist":false,"preventDuplicates":false}}}]
6978+
6979+
function quux () {
6980+
}
6981+
/**
6982+
*
6983+
*/
6984+
// Options: [{"tags":{"license":{"initialCommentsOnly":false,"mustExist":false,"preventDuplicates":true}}}]
6985+
6986+
/**
6987+
* @license MIT
6988+
*/
6989+
6990+
var a
6991+
6992+
/**
6993+
* @type {Array}
6994+
*/
6995+
// Options: [{"tags":{"license":{"initialCommentsOnly":true,"mustExist":false,"preventDuplicates":false}}}]
68396996
````
68406997
68416998
@@ -6844,7 +7001,7 @@ function quux () {
68447001
68457002
Requires a hyphen before the `@param` description.
68467003
6847-
<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-17"></a>
7004+
<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-18"></a>
68487005
#### Options
68497006
68507007
This rule takes one optional string argument. If it is `"always"` then a problem is raised when there is no hyphen before the description. If it is `"never"` then a problem is raised when there is a hyphen before the description. The default value is `"always"`.
@@ -6950,7 +7107,7 @@ function quux () {
69507107
Checks for presence of jsdoc comments, on class declarations as well as
69517108
functions.
69527109
6953-
<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-18"></a>
7110+
<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-19"></a>
69547111
#### Options
69557112
69567113
Accepts one optional options object with the following optional keys.
@@ -7968,10 +8125,10 @@ export default class Foo {
79688125
79698126
Requires that each `@param` tag has a `description` value.
79708127
7971-
<a name="eslint-plugin-jsdoc-rules-require-param-description-options-19"></a>
8128+
<a name="eslint-plugin-jsdoc-rules-require-param-description-options-20"></a>
79728129
#### Options
79738130
7974-
<a name="eslint-plugin-jsdoc-rules-require-param-description-options-19-contexts-4"></a>
8131+
<a name="eslint-plugin-jsdoc-rules-require-param-description-options-20-contexts-4"></a>
79758132
##### <code>contexts</code>
79768133
79778134
Set this to an array of strings representing the AST context
@@ -8088,10 +8245,10 @@ Requires that all function parameters have names.
80888245
>
80898246
> [JSDoc](https://jsdoc.app/tags-param.html#overview)
80908247

8091-
<a name="eslint-plugin-jsdoc-rules-require-param-name-options-20"></a>
8248+
<a name="eslint-plugin-jsdoc-rules-require-param-name-options-21"></a>
80928249
#### Options
80938250

8094-
<a name="eslint-plugin-jsdoc-rules-require-param-name-options-20-contexts-5"></a>
8251+
<a name="eslint-plugin-jsdoc-rules-require-param-name-options-21-contexts-5"></a>
80958252
##### <code>contexts</code>
80968253

80978254
Set this to an array of strings representing the AST context
@@ -8203,10 +8360,10 @@ function quux (foo) {
82038360

82048361
Requires that each `@param` tag has a `type` value.
82058362

8206-
<a name="eslint-plugin-jsdoc-rules-require-param-type-options-21"></a>
8363+
<a name="eslint-plugin-jsdoc-rules-require-param-type-options-22"></a>
82078364
#### Options
82088365

8209-
<a name="eslint-plugin-jsdoc-rules-require-param-type-options-21-contexts-6"></a>
8366+
<a name="eslint-plugin-jsdoc-rules-require-param-type-options-22-contexts-6"></a>
82108367
##### <code>contexts</code>
82118368

82128369
Set this to an array of strings representing the AST context
@@ -8319,7 +8476,7 @@ function quux (foo) {
83198476

83208477
Requires that all function parameters are documented.
83218478

8322-
<a name="eslint-plugin-jsdoc-rules-require-param-options-22"></a>
8479+
<a name="eslint-plugin-jsdoc-rules-require-param-options-23"></a>
83238480
#### Options
83248481

83258482
An options object accepts one optional property:
@@ -9563,10 +9720,10 @@ function quux () {
95639720
Requires that the `@returns` tag has a `description` value. The error
95649721
will not be reported if the return value is `void` or `undefined`.
95659722

9566-
<a name="eslint-plugin-jsdoc-rules-require-returns-description-options-23"></a>
9723+
<a name="eslint-plugin-jsdoc-rules-require-returns-description-options-24"></a>
95679724
#### Options
95689725

9569-
<a name="eslint-plugin-jsdoc-rules-require-returns-description-options-23-contexts-7"></a>
9726+
<a name="eslint-plugin-jsdoc-rules-require-returns-description-options-24-contexts-7"></a>
95709727
##### <code>contexts</code>
95719728

95729729
Set this to an array of strings representing the AST context
@@ -9701,10 +9858,10 @@ function quux () {
97019858

97029859
Requires that `@returns` tag has `type` value.
97039860

9704-
<a name="eslint-plugin-jsdoc-rules-require-returns-type-options-24"></a>
9861+
<a name="eslint-plugin-jsdoc-rules-require-returns-type-options-25"></a>
97059862
#### Options
97069863

9707-
<a name="eslint-plugin-jsdoc-rules-require-returns-type-options-24-contexts-8"></a>
9864+
<a name="eslint-plugin-jsdoc-rules-require-returns-type-options-25-contexts-8"></a>
97089865
##### <code>contexts</code>
97099866

97109867
Set this to an array of strings representing the AST context
@@ -9821,7 +9978,7 @@ Requires returns are documented.
98219978

98229979
Will also report if multiple `@returns` tags are present.
98239980

9824-
<a name="eslint-plugin-jsdoc-rules-require-returns-options-25"></a>
9981+
<a name="eslint-plugin-jsdoc-rules-require-returns-options-26"></a>
98259982
#### Options
98269983

98279984
- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
@@ -10420,7 +10577,7 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
1042010577
allow `#`, `.`, or `~` at the end (which is not allowed at the end of
1042110578
normal paths).
1042210579
10423-
<a name="eslint-plugin-jsdoc-rules-valid-types-options-26"></a>
10580+
<a name="eslint-plugin-jsdoc-rules-valid-types-options-27"></a>
1042410581
#### Options
1042510582
1042610583
- `allowEmptyNamepaths` (default: true) - Set to `false` to disallow

‎src/iterateJsdoc.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,7 @@ const iterateAllJsdocs = (iterator, ruleConfig) => {
516516
});
517517
if (lastCall && ruleConfig.exit) {
518518
ruleConfig.exit({
519+
context,
519520
state,
520521
utils,
521522
});

0 commit comments

Comments
 (0)