Skip to content

Commit 91344a4

Browse files
brettz9brettz9
committed
BREAKING CHANGE(require-description): remove noDefaults option and change contexts to always override defaults
Also reverting for `match-description` and adding tests for parents of `ClassExpression` and `ObjectExpression`
1 parent 00c13ce commit 91344a4

File tree

10 files changed

+167
-135
lines changed

10 files changed

+167
-135
lines changed

‎.README/rules/match-description.md

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -71,20 +71,15 @@ it by setting it to `false`.
7171

7272
##### `contexts`
7373

74-
Set this to a string or array of strings representing the AST context
74+
Set this to an array of strings representing the AST context
7575
where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
76-
77-
##### `noDefaults`
78-
79-
By default, `contexts` will permit `ArrowFunctionExpression`,
80-
`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
81-
have `contexts` override these.
76+
Overrides the defaults.
8277

8378
|||
8479
|---|---|
8580
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
8681
|Tags|N/A by default but see `tags` options|
8782
|Settings||
88-
|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
83+
|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
8984

9085
<!-- assertions matchDescription -->

‎.README/rules/require-description.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,17 @@ Requires that all functions have a description.
99

1010
An options object may have any of the following properties:
1111

12-
- `contexts` - Set to a string or array of strings representing the AST context
12+
- `contexts` - Set to an array of strings representing the AST context
1313
where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
14+
Overrides the defaults.
1415
- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
1516
block avoids the need for a `@description`.
16-
- `noDefaults` - By default, `contexts` will permit `ArrowFunctionExpression`,
17-
`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
18-
have `contexts` override these.
1917

2018
|||
2119
|---|---|
2220
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
2321
|Tags|`description`|
2422
|Aliases|`desc`|
25-
|Options|`contexts`, `exemptedBy`, `noDefaults`|
23+
|Options|`contexts`, `exemptedBy`|
2624

2725
<!-- assertions requireDescription -->

‎.README/rules/require-jsdoc.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,8 @@ be checked by the rule.
3434
- `FunctionExpression`
3535
- `MethodDefinition`
3636

37-
- `contexts` - Set this to a string or array of strings representing the additional
37+
- `contexts` - Set this to an array of strings representing the additional
3838
AST context where you wish the rule to be applied (e.g., `Property` for properties).
39-
Note that unlike `require-description` and `match-description`, this rule has no
40-
`noDefaults` option because its defaults are instead set up by `require`.
4139

4240
|||
4341
|---|---|

‎README.md

Lines changed: 52 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2354,26 +2354,38 @@ it by setting it to `false`.
23542354
<a name="eslint-plugin-jsdoc-rules-match-description-options-1-contexts"></a>
23552355
##### <code>contexts</code>
23562356

2357-
Set this to a string or array of strings representing the AST context
2357+
Set this to an array of strings representing the AST context
23582358
where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
2359-
2360-
<a name="eslint-plugin-jsdoc-rules-match-description-options-1-nodefaults"></a>
2361-
##### <code>noDefaults</code>
2362-
2363-
By default, `contexts` will permit `ArrowFunctionExpression`,
2364-
`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
2365-
have `contexts` override these.
2359+
Overrides the defaults.
23662360

23672361
|||
23682362
|---|---|
23692363
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
23702364
|Tags|N/A by default but see `tags` options|
23712365
|Settings||
2372-
|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
2366+
|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
23732367

23742368
The following patterns are considered problems:
23752369

23762370
````js
2371+
/**
2372+
* foo.
2373+
*/
2374+
const q = class {
2375+
2376+
}
2377+
// Options: [{"contexts":["ClassExpression"]}]
2378+
// Message: JSDoc description does not satisfy the regex pattern.
2379+
2380+
/**
2381+
* foo.
2382+
*/
2383+
const q = {
2384+
2385+
};
2386+
// Options: [{"contexts":["ObjectExpression"]}]
2387+
// Message: JSDoc description does not satisfy the regex pattern.
2388+
23772389
/**
23782390
* foo.
23792391
*/
@@ -2397,8 +2409,6 @@ function quux () {
23972409

23982410
}
23992411
// Options: [{"matchDescription":"[А-Я][А-я]+\\."}]
2400-
<<<<<<< HEAD
2401-
=======
24022412
// Message: JSDoc description does not satisfy the regex pattern.
24032413

24042414
/**
@@ -2407,12 +2417,7 @@ function quux () {
24072417
function quux () {
24082418

24092419
}
2410-
<<<<<<< HEAD
2411-
// Options: [{"tags":{"main description":"[А-Я][А-я]+\\.","param":true}}]
2412-
>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
2413-
=======
24142420
// Options: [{"mainDescription":"[А-Я][А-я]+\\.","tags":{"param":true}}]
2415-
>>>>>>> Switch "main description" on `tags` to its own option as `mainDescription`
24162421
// Message: JSDoc description does not satisfy the regex pattern.
24172422

24182423
/**
@@ -2556,8 +2561,6 @@ function quux () {
25562561

25572562
}
25582563
// Options: [{"tags":{"param":"[А-Я][А-я]+\\."}}]
2559-
<<<<<<< HEAD
2560-
=======
25612564
// Message: JSDoc description does not satisfy the regex pattern.
25622565

25632566
/**
@@ -2566,8 +2569,7 @@ function quux () {
25662569
class quux {
25672570

25682571
}
2569-
// Options: [{"contexts":["ClassDeclaration"],"noDefaults":true}]
2570-
>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
2572+
// Options: [{"contexts":["ClassDeclaration"]}]
25712573
// Message: JSDoc description does not satisfy the regex pattern.
25722574

25732575
class MyClass {
@@ -2576,7 +2578,7 @@ class MyClass {
25762578
*/
25772579
myClassField = 1
25782580
}
2579-
// Options: [{"contexts":["ClassProperty"],"noDefaults":true}]
2581+
// Options: [{"contexts":["ClassProperty"]}]
25802582
// Message: JSDoc description does not satisfy the regex pattern.
25812583

25822584
/**
@@ -2585,7 +2587,7 @@ class MyClass {
25852587
interface quux {
25862588

25872589
}
2588-
// Options: [{"contexts":["TSInterfaceDeclaration"],"noDefaults":true}]
2590+
// Options: [{"contexts":["TSInterfaceDeclaration"]}]
25892591
// Message: JSDoc description does not satisfy the regex pattern.
25902592

25912593
const myObject = {
@@ -2594,7 +2596,7 @@ const myObject = {
25942596
*/
25952597
myProp: true
25962598
};
2597-
// Options: [{"contexts":["Property"],"noDefaults":true}]
2599+
// Options: [{"contexts":["Property"]}]
25982600
// Message: JSDoc description does not satisfy the regex pattern.
25992601
````
26002602

@@ -2739,7 +2741,6 @@ function quux () {
27392741
class quux {
27402742

27412743
}
2742-
// Message: JSDoc description does not satisfy the regex pattern.
27432744

27442745
/**
27452746
* foo.
@@ -2755,23 +2756,39 @@ class MyClass {
27552756
*/
27562757
myClassField = 1
27572758
}
2758-
// Options: [{"contexts":["ClassProperty"],"noDefaults":true}]
2759+
// Options: [{"contexts":["ClassProperty"]}]
27592760

27602761
/**
27612762
* Foo.
27622763
*/
27632764
interface quux {
27642765

27652766
}
2766-
// Options: [{"contexts":["TSInterfaceDeclaration"],"noDefaults":true}]
2767+
// Options: [{"contexts":["TSInterfaceDeclaration"]}]
27672768

27682769
const myObject = {
27692770
/**
27702771
* Bad description
27712772
*/
27722773
myProp: true
27732774
};
2774-
// Options: [{"contexts":[],"noDefaults":true}]
2775+
// Options: [{"contexts":[]}]
2776+
2777+
/**
2778+
* foo.
2779+
*/
2780+
const q = class {
2781+
2782+
}
2783+
// Options: [{"contexts":[]}]
2784+
2785+
/**
2786+
* foo.
2787+
*/
2788+
const q = {
2789+
2790+
};
2791+
// Options: [{"contexts":[]}]
27752792
````
27762793

27772794

@@ -3511,20 +3528,18 @@ Requires that all functions have a description.
35113528

35123529
An options object may have any of the following properties:
35133530

3514-
- `contexts` - Set to a string or array of strings representing the AST context
3531+
- `contexts` - Set to an array of strings representing the AST context
35153532
where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
3533+
Overrides the defaults.
35163534
- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
35173535
block avoids the need for a `@description`.
3518-
- `noDefaults` - By default, `contexts` will permit `ArrowFunctionExpression`,
3519-
`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
3520-
have `contexts` override these.
35213536

35223537
|||
35233538
|---|---|
35243539
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
35253540
|Tags|`description`|
35263541
|Aliases|`desc`|
3527-
|Options|`contexts`, `exemptedBy`, `noDefaults`|
3542+
|Options|`contexts`, `exemptedBy`|
35283543

35293544
The following patterns are considered problems:
35303545

@@ -3543,7 +3558,7 @@ function quux () {
35433558
class quux {
35443559

35453560
}
3546-
// Options: [{"contexts":"ClassDeclaration"}]
3561+
// Options: [{"contexts":["ClassDeclaration"]}]
35473562
// Message: Missing JSDoc @description declaration.
35483563

35493564
/**
@@ -3552,7 +3567,7 @@ class quux {
35523567
class quux {
35533568

35543569
}
3555-
// Options: [{"contexts":"ClassDeclaration","noDefaults":true}]
3570+
// Options: [{"contexts":["ClassDeclaration"]}]
35563571
// Message: Missing JSDoc @description declaration.
35573572

35583573
/**
@@ -3578,9 +3593,8 @@ function quux () {
35783593
interface quux {
35793594

35803595
}
3581-
// Options: [{"contexts":["TSInterfaceDeclaration"],"noDefaults":true}]
3596+
// Options: [{"contexts":["TSInterfaceDeclaration"]}]
35823597
// Message: Missing JSDoc @description declaration.
3583-
<<<<<<< HEAD
35843598

35853599
/**
35863600
*
@@ -3599,8 +3613,6 @@ var quux = {
35993613
};
36003614
// Options: [{"contexts":["ObjectExpression"]}]
36013615
// Message: Missing JSDoc @description declaration.
3602-
=======
3603-
>>>>>>> fix(match-description): tighten default regex to require punctuation at the end even if only a single character
36043616
````
36053617

36063618
The following patterns are not considered problems:
@@ -3646,7 +3658,7 @@ class quux {
36463658
function quux () {
36473659

36483660
}
3649-
// Options: [{"noDefaults":true}]
3661+
// Options: [{"contexts":["ClassDeclaration"]}]
36503662

36513663
/**
36523664
* @type {MyCallback}
@@ -3662,7 +3674,6 @@ function quux () {
36623674
interface quux {
36633675

36643676
}
3665-
<<<<<<< HEAD
36663677

36673678
/**
36683679
*
@@ -3677,9 +3688,6 @@ var quux = class {
36773688
var quux = {
36783689

36793690
};
3680-
=======
3681-
// Message: Missing JSDoc @description declaration.
3682-
>>>>>>> fix(match-description): tighten default regex to require punctuation at the end even if only a single character
36833691
````
36843692

36853693

@@ -3947,10 +3955,8 @@ be checked by the rule.
39473955
- `FunctionExpression`
39483956
- `MethodDefinition`
39493957

3950-
- `contexts` - Set this to a string or array of strings representing the additional
3958+
- `contexts` - Set this to an array of strings representing the additional
39513959
AST context where you wish the rule to be applied (e.g., `Property` for properties).
3952-
Note that unlike `require-description` and `match-description`, this rule has no
3953-
`noDefaults` option because its defaults are instead set up by `require`.
39543960

39553961
|||
39563962
|---|---|

‎src/jsdocUtils.js

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -493,22 +493,16 @@ const parseClosureTemplateTag = (tag) => {
493493
* @returns {string[]}
494494
*/
495495
const enforcedContexts = (context, defaultContexts) => {
496-
/* istanbul ignore next */
497-
const defltContexts = defaultContexts === true ? [
498-
'ArrowFunctionExpression',
499-
'FunctionDeclaration',
500-
'FunctionExpression'
501-
] : defaultContexts;
502496
const {
503-
noDefaults,
504-
contexts: ctxts = []
497+
/* istanbul ignore next */
498+
contexts = defaultContexts === true ? [
499+
'ArrowFunctionExpression',
500+
'FunctionDeclaration',
501+
'FunctionExpression'
502+
] : defaultContexts
505503
} = context.options[0] || {};
506504

507-
const contexts = typeof ctxts === 'string' ? [ctxts] : ctxts;
508-
509-
return noDefaults ?
510-
contexts :
511-
[...new Set([...defltContexts, ...contexts])];
505+
return contexts;
512506
};
513507

514508
const getContextObject = (contexts, checkJsdoc) => {

‎src/rules/matchDescription.js

Lines changed: 4 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -71,17 +71,10 @@ export default iterateJsdoc(({
7171
additionalProperties: false,
7272
properties: {
7373
contexts: {
74-
oneOf: [
75-
{
76-
items: {
77-
type: 'string'
78-
},
79-
type: 'array'
80-
},
81-
{
82-
type: 'string'
83-
}
84-
]
74+
items: {
75+
type: 'string'
76+
},
77+
type: 'array'
8578
},
8679
mainDescription: {
8780
oneOf: [
@@ -98,10 +91,6 @@ export default iterateJsdoc(({
9891
format: 'regex',
9992
type: 'string'
10093
},
101-
noDefaults: {
102-
default: false,
103-
type: 'boolean'
104-
},
10594
tags: {
10695
patternProperties: {
10796
'.*': {

0 commit comments

Comments
 (0)