Skip to content

Commit 371de2e

Browse files
brettz9brettz9
committed
INCOMPLETE: expand valid-types tags; check if no-undefined-types and check-types should be checking borrows and namepath types; flesh out require-jsdoc including scopes and tags/aliases
- Fix: Remove `parameter` as accepted synonym for `@param` (not listed at site); affects `check-tag-names` and various param rules - Enhancement: Have `require-hyphen-before-param-description` check `tagNamePreference` setting - Refactoring: Avoid checking for preferred name for `example` (as there are no official synonyms) - Refactoring: Toward resolving gajus#216, group settings by which rules use them - Refactoring: Rename `isLink` inner function to `isInlineTag` for accuracy - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules - Docs: Observation about `Object.create(null)` and `check-types`
1 parent d91cc9c commit 371de2e

22 files changed

+438
-31
lines changed

‎.README/README.md

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,9 +121,26 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a
121121
}
122122
```
123123

124+
This setting is utilized by the the rule for tag name checking
125+
(`check-tag-names`) as well as in the `@param` and `@require` rules:
126+
127+
- `check-param-names`
128+
- `check-tag-names`
129+
- `require-hyphen-before-param-description`
130+
- `require-description`
131+
- `require-param`
132+
- `require-param-description`
133+
- `require-param-name`
134+
- `require-param-type`
135+
- `require-returns`
136+
- `require-returns-check`
137+
- `require-returns-description`
138+
- `require-returns-type`
139+
124140
### Additional Tag Names
125141

126-
Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc tags. The format of the configuration is as follows:
142+
Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc
143+
tags in the rule `check-tag-names`. The format of the configuration is as follows:
127144

128145
```json
129146
{
@@ -166,6 +183,16 @@ The format of the configuration is as follows:
166183
}
167184
```
168185

186+
### Settings to Configure `valid-types`
187+
188+
* `settings.jsdoc.allowEmptyNamepaths` - Set to `false` to disallow
189+
empty name paths with `@callback`, `@event`, `@listens`, `@fires`,
190+
or `@emits` (these might often be expected to have an accompanying
191+
name path, though they have some indicative value without one)
192+
* `settings.jsdoc.checkSeesForNamepaths` - Set this to `true` to insist
193+
that `@see` only use name paths (the tag is normally permitted to
194+
allow other text)
195+
169196
### Settings to Configure `check-examples`
170197

171198
The settings below all impact the `check-examples` rule and default to
@@ -264,6 +291,7 @@ Finally, the following rule pertains to inline disable directives:
264291
{"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}
265292
{"gitdown": "include", "file": "./rules/require-description.md"}
266293
{"gitdown": "include", "file": "./rules/require-example.md"}
294+
{"gitdown": "include", "file": "./rules/require-jsdoc.md"}
267295
{"gitdown": "include", "file": "./rules/require-hyphen-before-param-description.md"}
268296
{"gitdown": "include", "file": "./rules/require-param-description.md"}
269297
{"gitdown": "include", "file": "./rules/require-param-name.md"}

‎.README/rules/check-examples.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,6 @@ command.
2323
|||
2424
|---|---|
2525
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
26-
|Tags|`param`|
26+
|Tags|`example`|
2727

2828
<!-- assertions checkExamples -->

‎.README/rules/check-types.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ new String('lard') // String {0: "l", 1: "a", 2: "r", 3: "d", length: 4}
3030
new String('lard') === 'lard' // false
3131
```
3232

33-
To make things more confusing, there are also object literals and object Objects. But object literals are still static Objects and object Objects are instantiated Objects. So an object primitive is still an object Object.
33+
To make things more confusing, there are also object literals and object Objects. But object literals are still static Objects and object Objects are instantiated Objects. So an object primitive is still an object Object. (`Object.create(null)` objects are not, however.)
3434

3535
Basically, for primitives, we want to define the type as a primitive, because that's what we use in 99.9% of cases. For everything else, we use the type rather than the primitive. Otherwise it would all just be `{object}`.
3636

@@ -47,8 +47,9 @@ Number | **number** | **number** | `(41) instanceof Number` -> **`false`**
4747
String | **string** | **string** | `("test") instanceof String` -> **`false`**
4848

4949
|||
50-
|---|---|
50+
|---|---|---|
5151
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
5252
|Tags|`class`, `constant`, `enum`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`|
53+
|Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`|
5354

5455
<!-- assertions checkTypes -->

‎.README/rules/no-undefined-types.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
11
### `no-undefined-types`
22

3-
Checks that types in jsdoc comments are defined. This can be used to check unimported types.
3+
Checks that types in jsdoc comments are defined. This can be used to check
4+
unimported types.
45

5-
When enabling this rule, types in jsdoc comments will resolve as used variables, i.e. will not be marked as unused by `no-unused-vars`.
6+
When enabling this rule, types in jsdoc comments will resolve as used
7+
variables, i.e. will not be marked as unused by `no-unused-vars`.
68

79

810
|||
911
|---|---|
1012
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
11-
|Tags|`param`, `returns`|
12-
13+
|Tags|`param`, `returns`, `type`, `typedef`, `throws`, `property`, `constant`, `member`, `module`, `namespace`, `enum`, `implements`, `yields`|
14+
|Aliases|`arg`, `argument`, `return`, `yield`, `var`, `const`, `exception`
15+
|Closure-only|`package`, `private`, `protected`, `public`, `static`
1316
<!-- assertions noUndefinedTypes -->

‎.README/rules/require-description-complete-sentence.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,6 @@ Requires that block description and tag description are written in complete sent
1111
|---|---|
1212
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
1313
|Tags|`param`, `returns`|
14+
|Aliases|`arg`, `argument`, `return`|
1415

1516
<!-- assertions requireDescriptionCompleteSentence -->

‎.README/rules/require-description.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Requires that all functions have a description.
88
|||
99
|---|---|
1010
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
11-
|Tags|`class`, `example`|
11+
|Tags|`description`|
12+
|Aliases|`desc`|
1213

1314
<!-- assertions requireDescription -->

‎.README/rules/require-hyphen-before-param-description.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,6 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
88
|---|---|
99
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
1010
|Tags|`param`|
11+
|Aliases|`arg`, `argument`|
1112

1213
<!-- assertions requireHyphenBeforeParamDescription -->

‎.README/rules/require-jsdoc.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `require-jsdoc`
2+
3+
Checks for presence of jsdoc comments, across a variety of contexts.
4+
5+
|||
6+
|---|---|
7+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
8+
|Tags|N/A|
9+
10+
<!-- assertions requireJsdoc -->

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Requires that `@param` tag has `description` value.
66
|---|---|
77
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
88
|Tags|`param`|
9+
|Aliases|`arg`, `argument`|
910

1011
<!-- assertions requireParamDescription -->

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,6 @@ Requires that all function parameters have name.
1010
|---|---|
1111
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
1212
|Tags|`param`|
13+
|Aliases|`arg`, `argument`|
1314

1415
<!-- assertions requireParamName -->

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Requires that `@param` tag has `type` value.
66
|---|---|
77
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
88
|Tags|`param`|
9+
|Aliases|`arg`, `argument`|
910

1011
<!-- assertions requireParamType -->

‎.README/rules/require-param.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Requires that all function parameters are documented.
66
|---|---|
77
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
88
|Tags|`param`|
9+
|Aliases|`arg`, `argument`|
910

1011
<!-- assertions requireParam -->

‎.README/rules/require-returns-check.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Checks if the return expression exists in function body and in the comment.
66
|---|---|
77
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
88
|Tags|`returns`|
9+
|Aliases|`return`|
910

1011
<!-- assertions requireReturnsCheck -->

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Requires that `@returns` tag has `description` value.
66
|---|---|
77
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
88
|Tags|`returns`|
9+
|Aliases|`return`|
910

1011
<!-- assertions requireReturnsDescription -->

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Requires that `@returns` tag has `type` value.
66
|---|---|
77
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
88
|Tags|`returns`|
9+
|Aliases|`return`|
910

1011
<!-- assertions requireReturnsType -->

‎.README/rules/require-returns.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Requires returns are documented.
66
|---|---|
77
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
88
|Tags|`returns`|
9+
|Aliases|`return`|
910

1011
<!-- assertions requireReturns -->

0 commit comments

Comments
 (0)