Skip to content

Commit 3b61dcc

Browse files
brettz9brettz9
committed
feat(match-description): report line number and allow reporting multiple errors when main description validation fails
1 parent b1b231b commit 3b61dcc

File tree

4 files changed

+291
-16
lines changed

4 files changed

+291
-16
lines changed

‎.README/rules/match-description.md

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,14 +50,39 @@ tag should be linted with the `matchDescription` value (or the default).
5050
}
5151
```
5252

53+
If you wish to override the main function description without changing the
54+
default `mainDescription`, you may use `tags` with `main description`:
5355

54-
By default, only the main function description is linted.
56+
```js
57+
{
58+
'jsdoc/match-description': ['error', {tags: {
59+
'main description': '[A-Z].*\\.',
60+
param: true,
61+
returns: true
62+
}}]
63+
}
64+
```
65+
66+
There is no need to add `"main description": true`, as by default, the main
67+
function (and only the main function) is linted, though you may disable checking
68+
it by setting it to `false`.
69+
70+
##### `contexts`
71+
72+
Set this to a string or array of strings representing the AST context
73+
where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
74+
75+
##### `noDefaults`
76+
77+
By default, `contexts` will permit `ArrowFunctionExpression`,
78+
`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
79+
have `contexts` override these.
5580

5681
|||
5782
|---|---|
58-
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
83+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
5984
|Tags|N/A by default but see `tags` options|
6085
|Settings||
61-
|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
86+
|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
6287

6388
<!-- assertions matchDescription -->

‎README.md

Lines changed: 100 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2332,15 +2332,42 @@ tag should be linted with the `matchDescription` value (or the default).
23322332
}
23332333
```
23342334

2335+
If you wish to override the main function description without changing the
2336+
default `mainDescription`, you may use `tags` with `main description`:
23352337

2336-
By default, only the main function description is linted.
2338+
```js
2339+
{
2340+
'jsdoc/match-description': ['error', {tags: {
2341+
'main description': '[A-Z].*\\.',
2342+
param: true,
2343+
returns: true
2344+
}}]
2345+
}
2346+
```
2347+
2348+
There is no need to add `"main description": true`, as by default, the main
2349+
function (and only the main function) is linted, though you may disable checking
2350+
it by setting it to `false`.
2351+
2352+
<a name="eslint-plugin-jsdoc-rules-match-description-options-1-contexts"></a>
2353+
##### <code>contexts</code>
2354+
2355+
Set this to a string or array of strings representing the AST context
2356+
where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
2357+
2358+
<a name="eslint-plugin-jsdoc-rules-match-description-options-1-nodefaults"></a>
2359+
##### <code>noDefaults</code>
2360+
2361+
By default, `contexts` will permit `ArrowFunctionExpression`,
2362+
`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
2363+
have `contexts` override these.
23372364

23382365
|||
23392366
|---|---|
2340-
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
2367+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
23412368
|Tags|N/A by default but see `tags` options|
23422369
|Settings||
2343-
|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
2370+
|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
23442371

23452372
The following patterns are considered problems:
23462373

@@ -2368,6 +2395,18 @@ function quux () {
23682395

23692396
}
23702397
// Options: [{"matchDescription":"[А-Я][А-я]+\\."}]
2398+
<<<<<<< HEAD
2399+
=======
2400+
// Message: JSDoc description does not satisfy the regex pattern.
2401+
2402+
/**
2403+
* тест.
2404+
*/
2405+
function quux () {
2406+
2407+
}
2408+
// Options: [{"tags":{"main description":"[А-Я][А-я]+\\.","param":true}}]
2409+
>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
23712410
// Message: JSDoc description does not satisfy the regex pattern.
23722411

23732412
/**
@@ -2389,6 +2428,28 @@ function quux (foo) {
23892428
// Options: [{"tags":{"param":true}}]
23902429
// Message: JSDoc description does not satisfy the regex pattern.
23912430

2431+
/**
2432+
* Foo
2433+
*
2434+
* @param foo foo.
2435+
*/
2436+
function quux (foo) {
2437+
2438+
}
2439+
// Options: [{"tags":{"main description":"^[a-zA-Z]*$","param":true}}]
2440+
// Message: JSDoc description does not satisfy the regex pattern.
2441+
2442+
/**
2443+
* Foo
2444+
*
2445+
* @param foo foo.
2446+
*/
2447+
function quux (foo) {
2448+
2449+
}
2450+
// Options: [{"tags":{"main description":false,"param":true}}]
2451+
// Message: JSDoc description does not satisfy the regex pattern.
2452+
23922453
/**
23932454
* Foo.
23942455
*
@@ -2489,6 +2550,18 @@ function quux () {
24892550

24902551
}
24912552
// Options: [{"tags":{"param":"[А-Я][А-я]+\\."}}]
2553+
<<<<<<< HEAD
2554+
=======
2555+
// Message: JSDoc description does not satisfy the regex pattern.
2556+
2557+
/**
2558+
* foo.
2559+
*/
2560+
class quux {
2561+
2562+
}
2563+
// Options: [{"contexts":["ClassDeclaration"],"noDefaults":true}]
2564+
>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
24922565
// Message: JSDoc description does not satisfy the regex pattern.
24932566
````
24942567

@@ -2618,6 +2691,30 @@ function quux () {
26182691
function quux () {
26192692

26202693
}
2694+
2695+
/**
2696+
* foo.
2697+
*/
2698+
function quux () {
2699+
2700+
}
2701+
// Options: [{"tags":{"main description":false}}]
2702+
2703+
/**
2704+
* foo.
2705+
*/
2706+
class quux {
2707+
2708+
}
2709+
// Message: JSDoc description does not satisfy the regex pattern.
2710+
2711+
/**
2712+
* foo.
2713+
*/
2714+
class quux {
2715+
2716+
}
2717+
// Options: [{"tags":{"main description":true}}]
26212718
````
26222719

26232720

‎src/rules/matchDescription.js

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,13 @@ export default iterateJsdoc(({
1212
const options = context.options[0] || {};
1313

1414
const validateDescription = (description, tag) => {
15+
const tagName = tag.tag;
16+
const tagOptions = options.tags || {};
17+
if (tagOptions[tagName] === false) {
18+
return;
19+
}
1520
const regex = new RegExp(
16-
(tag && typeof options.tags[tag] === 'string' ? options.tags[tag] :
21+
(typeof tagOptions[tagName] === 'string' ? tagOptions[tagName] :
1722
options.matchDescription
1823

1924
// If supporting Node >= 10, we could loosen to this for the
@@ -23,16 +28,16 @@ export default iterateJsdoc(({
2328
);
2429

2530
if (!regex.test(description)) {
26-
report('JSDoc description does not satisfy the regex pattern.');
27-
28-
return true;
31+
report('JSDoc description does not satisfy the regex pattern.', null, tag);
2932
}
30-
31-
return false;
3233
};
3334

34-
if (jsdoc.description && validateDescription(jsdoc.description)) {
35-
return;
35+
if (jsdoc.description) {
36+
validateDescription(jsdoc.description, {
37+
// Add one as description would typically be into block
38+
line: jsdoc.line + 1,
39+
tag: 'main description'
40+
});
3641
}
3742

3843
if (!options.tags || !Object.keys(options.tags).length) {
@@ -47,18 +52,36 @@ export default iterateJsdoc(({
4752
tags.some((tag) => {
4853
const description = _.trimStart(tag.description, '- ');
4954

50-
return validateDescription(description, tag.tag);
55+
return validateDescription(description, tag);
5156
});
5257
}, {
58+
contextDefaults: true,
5359
meta: {
5460
schema: [
5561
{
5662
additionalProperties: false,
5763
properties: {
64+
contexts: {
65+
oneOf: [
66+
{
67+
items: {
68+
type: 'string'
69+
},
70+
type: 'array'
71+
},
72+
{
73+
type: 'string'
74+
}
75+
]
76+
},
5877
matchDescription: {
5978
format: 'regex',
6079
type: 'string'
6180
},
81+
noDefaults: {
82+
default: false,
83+
type: 'boolean'
84+
},
6285
tags: {
6386
patternProperties: {
6487
'.*': {
@@ -68,7 +91,6 @@ export default iterateJsdoc(({
6891
type: 'string'
6992
},
7093
{
71-
enum: [true],
7294
type: 'boolean'
7395
}
7496
]

0 commit comments

Comments
 (0)