Skip to content

Commit 946cbe8

Browse files
thsmithsmi
committed
Merge remote-tracking branch 'upstream/master'
2 parents 24597b4 + 0f4a878 commit 946cbe8

18 files changed

+578
-12
lines changed

‎.README/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,11 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
1414

1515
| `eslint-plugin-jsdoc` | `jscs-jsdoc` |
1616
| --- | --- |
17+
| [`check-alignment`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-alignment) | N/A |
1718
| [`check-examples`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-examples) | N/A |
19+
| [`check-indentation`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-indentation) | N/A |
1820
| [`check-param-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-param-names) | [`checkParamNames`](https://github.com/jscs-dev/jscs-jsdoc#checkparamnames) |
21+
| [`check-syntax`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-syntax) | N/A |
1922
| [`check-tag-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-tag-names) | N/A ~ [`checkAnnotations`](https://github.com/jscs-dev/jscs-jsdoc#checkannotations) |
2023
| [`check-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-types) | [`checkTypes`](https://github.com/jscs-dev/jscs-jsdoc#checktypes) |
2124
| [`newline-after-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-newline-after-description) | [`requireNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirenewlineafterdescription) and [`disallowNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#disallownewlineafterdescription) |
@@ -71,8 +74,11 @@ Finally, enable all of the rules that you would like to use.
7174
```json
7275
{
7376
"rules": {
77+
"jsdoc/check-alignment": 1,
7478
"jsdoc/check-examples": 1,
79+
"jsdoc/check-indentation": 1,
7580
"jsdoc/check-param-names": 1,
81+
"jsdoc/check-syntax": 1,
7682
"jsdoc/check-tag-names": 1,
7783
"jsdoc/check-types": 1,
7884
"jsdoc/newline-after-description": 1,
@@ -245,8 +251,11 @@ Finally, the following rule pertains to inline disable directives:
245251

246252
## Rules
247253

254+
{"gitdown": "include", "file": "./rules/check-alignment.md"}
248255
{"gitdown": "include", "file": "./rules/check-examples.md"}
256+
{"gitdown": "include", "file": "./rules/check-indentation.md"}
249257
{"gitdown": "include", "file": "./rules/check-param-names.md"}
258+
{"gitdown": "include", "file": "./rules/check-syntax.md"}
250259
{"gitdown": "include", "file": "./rules/check-tag-names.md"}
251260
{"gitdown": "include", "file": "./rules/check-types.md"}
252261
{"gitdown": "include", "file": "./rules/newline-after-description.md"}

‎.README/rules/check-alignment.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `check-alignment`
2+
3+
Reports invalid alignment of JSDoc block asterisks.
4+
5+
|||
6+
|---|---|
7+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
8+
|Tags|N/A|
9+
10+
<!-- assertions checkAlignment -->

‎.README/rules/check-indentation.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `check-indentation`
2+
3+
Reports invalid padding inside JSDoc block.
4+
5+
|||
6+
|---|---|
7+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
8+
|Tags|N/A|
9+
10+
<!-- assertions checkIndentation -->

‎.README/rules/check-syntax.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `check-syntax`
2+
3+
Reports against Google Closure Compiler syntax.
4+
5+
|||
6+
|---|---|
7+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
8+
|Tags|N/A|
9+
10+
<!-- assertions checkSyntax -->

‎README.md

Lines changed: 220 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,11 @@ JSDoc linting rules for ESLint.
1717
* [Allow `@override` Without Accompanying `@param` Tags](#eslint-plugin-jsdoc-settings-allow-override-without-accompanying-param-tags)
1818
* [Settings to Configure `check-examples`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-examples)
1919
* [Rules](#eslint-plugin-jsdoc-rules)
20+
* [`check-alignment`](#eslint-plugin-jsdoc-rules-check-alignment)
2021
* [`check-examples`](#eslint-plugin-jsdoc-rules-check-examples)
22+
* [`check-indentation`](#eslint-plugin-jsdoc-rules-check-indentation)
2123
* [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names)
24+
* [`check-syntax`](#eslint-plugin-jsdoc-rules-check-syntax)
2225
* [`check-tag-names`](#eslint-plugin-jsdoc-rules-check-tag-names)
2326
* [`check-types`](#eslint-plugin-jsdoc-rules-check-types)
2427
* [`newline-after-description`](#eslint-plugin-jsdoc-rules-newline-after-description)
@@ -45,8 +48,11 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
4548

4649
| `eslint-plugin-jsdoc` | `jscs-jsdoc` |
4750
| --- | --- |
51+
| [`check-alignment`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-alignment) | N/A |
4852
| [`check-examples`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-examples) | N/A |
53+
| [`check-indentation`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-indentation) | N/A |
4954
| [`check-param-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-param-names) | [`checkParamNames`](https://github.com/jscs-dev/jscs-jsdoc#checkparamnames) |
55+
| [`check-syntax`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-syntax) | N/A |
5056
| [`check-tag-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-tag-names) | N/A ~ [`checkAnnotations`](https://github.com/jscs-dev/jscs-jsdoc#checkannotations) |
5157
| [`check-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-types) | [`checkTypes`](https://github.com/jscs-dev/jscs-jsdoc#checktypes) |
5258
| [`newline-after-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-newline-after-description) | [`requireNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirenewlineafterdescription) and [`disallowNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#disallownewlineafterdescription) |
@@ -104,8 +110,11 @@ Finally, enable all of the rules that you would like to use.
104110
```json
105111
{
106112
"rules": {
113+
"jsdoc/check-alignment": 1,
107114
"jsdoc/check-examples": 1,
115+
"jsdoc/check-indentation": 1,
108116
"jsdoc/check-param-names": 1,
117+
"jsdoc/check-syntax": 1,
109118
"jsdoc/check-tag-names": 1,
110119
"jsdoc/check-types": 1,
111120
"jsdoc/newline-after-description": 1,
@@ -285,6 +294,87 @@ Finally, the following rule pertains to inline disable directives:
285294
<a name="eslint-plugin-jsdoc-rules"></a>
286295
## Rules
287296

297+
<a name="eslint-plugin-jsdoc-rules-check-alignment"></a>
298+
### <code>check-alignment</code>
299+
300+
Reports invalid alignment of JSDoc block asterisks.
301+
302+
|||
303+
|---|---|
304+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
305+
|Tags|N/A|
306+
307+
The following patterns are considered problems:
308+
309+
````js
310+
/**
311+
* @param {Number} foo
312+
*/
313+
function quux (foo) {
314+
315+
}
316+
// Message: Expected JSDoc block to be aligned.
317+
318+
/**
319+
* @param {Number} foo
320+
*/
321+
function quux (foo) {
322+
323+
}
324+
// Message: Expected JSDoc block to be aligned.
325+
326+
/**
327+
* @param {Number} foo
328+
*/
329+
function quux (foo) {
330+
331+
}
332+
// Message: Expected JSDoc block to be aligned.
333+
334+
/**
335+
* @param {Number} foo
336+
*/
337+
function quux (foo) {
338+
339+
}
340+
// Message: Expected JSDoc block to be aligned.
341+
342+
/**
343+
* @param {Number} foo
344+
*/
345+
function quux (foo) {
346+
347+
}
348+
// Message: Expected JSDoc block to be aligned.
349+
````
350+
351+
The following patterns are not considered problems:
352+
353+
````js
354+
/**
355+
* Desc
356+
*
357+
* @param {Number} foo
358+
*/
359+
function quux (foo) {
360+
361+
}
362+
363+
/**
364+
* Desc
365+
*
366+
* @param {{
367+
foo: Bar,
368+
bar: Baz
369+
* }} foo
370+
*
371+
*/
372+
function quux (foo) {
373+
374+
}
375+
````
376+
377+
288378
<a name="eslint-plugin-jsdoc-rules-check-examples"></a>
289379
### <code>check-examples</code>
290380

@@ -485,6 +575,46 @@ function quux () {}
485575
````
486576

487577

578+
<a name="eslint-plugin-jsdoc-rules-check-indentation"></a>
579+
### <code>check-indentation</code>
580+
581+
Reports invalid padding inside JSDoc block.
582+
583+
|||
584+
|---|---|
585+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
586+
|Tags|N/A|
587+
588+
The following patterns are considered problems:
589+
590+
````js
591+
/**
592+
* foo
593+
*
594+
* @param bar
595+
* baz
596+
*/
597+
function quux () {
598+
599+
}
600+
// Message: There must be no indentation.
601+
````
602+
603+
The following patterns are not considered problems:
604+
605+
````js
606+
/**
607+
* foo
608+
*
609+
* @param bar
610+
* baz
611+
*/
612+
function quux () {
613+
614+
}
615+
````
616+
617+
488618
<a name="eslint-plugin-jsdoc-rules-check-param-names"></a>
489619
### <code>check-param-names</code>
490620

@@ -663,6 +793,40 @@ function quux ({
663793

664794
Likewise for the pattern `[a, b]` which is an [`ArrayPattern`](https://github.com/estree/estree/blob/master/es2015.md#arraypattern).
665795

796+
<a name="eslint-plugin-jsdoc-rules-check-syntax"></a>
797+
### <code>check-syntax</code>
798+
799+
Reports against Google Closure Compiler syntax.
800+
801+
|||
802+
|---|---|
803+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
804+
|Tags|N/A|
805+
806+
The following patterns are considered problems:
807+
808+
````js
809+
/**
810+
* @param {string=} foo
811+
*/
812+
function quux (foo) {
813+
814+
}
815+
// Message: Syntax should not be Google Closure Compiler style.
816+
````
817+
818+
The following patterns are not considered problems:
819+
820+
````js
821+
/**
822+
* @param {string} [foo]
823+
*/
824+
function quux (foo) {
825+
826+
}
827+
````
828+
829+
666830
<a name="eslint-plugin-jsdoc-rules-check-tag-names"></a>
667831
### <code>check-tag-names</code>
668832

@@ -781,6 +945,15 @@ function quux (foo) {
781945
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
782946
// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "arg".
783947

948+
/**
949+
* @param foo
950+
*/
951+
function quux (foo) {
952+
953+
}
954+
// Settings: {"jsdoc":{"tagNamePreference":{"param":"parameter"}}}
955+
// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "parameter".
956+
784957
/**
785958
* @bar foo
786959
*/
@@ -843,7 +1016,7 @@ function quux (foo) {
8431016
}
8441017
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["baz","bar"]}}}
8451018

846-
/**
1019+
/**
8471020
* @abstract
8481021
* @access
8491022
* @alias
@@ -931,9 +1104,9 @@ RegExp
9311104
<a name="eslint-plugin-jsdoc-rules-check-types-why-not-capital-case-everything"></a>
9321105
#### Why not capital case everything?
9331106

934-
Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`.
1107+
Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`.
9351108

936-
Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do.
1109+
Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do.
9371110

9381111
So in a sense, there two types of strings in Javascript; `{string}` literals, also called primitives and `{String}` Objects. We use the primitives because it's easier to write and uses less memory. `{String}` and `{string}` are technically both valid, but they are not the same.
9391112

@@ -1035,6 +1208,30 @@ function quux (foo, bar, baz) {
10351208
*/
10361209
function quux (foo, bar, baz) {
10371210

1211+
}
1212+
1213+
/**
1214+
* @param {typeof bar} foo
1215+
*/
1216+
function qux(foo) {
1217+
}
1218+
1219+
/**
1220+
* @param {import('./foo').bar.baz} foo
1221+
*/
1222+
function qux(foo) {
1223+
}
1224+
1225+
/**
1226+
* @param {(x: number, y: string) => string} foo
1227+
*/
1228+
function qux(foo) {
1229+
}
1230+
1231+
/**
1232+
* @param {() => string} foo
1233+
*/
1234+
function qux(foo) {
10381235
}
10391236
````
10401237

@@ -2284,6 +2481,16 @@ function quux (foo) {
22842481
*/
22852482
const quux = () => {}
22862483
// Message: Present JSDoc @returns declaration but not available return expression in function.
2484+
2485+
/**
2486+
* @returns {undefined} Foo.
2487+
* @returns {String} Foo.
2488+
*/
2489+
function quux () {
2490+
2491+
return foo;
2492+
}
2493+
// Message: Found more than one @returns declaration.
22872494
````
22882495

22892496
The following patterns are not considered problems:
@@ -2324,15 +2531,23 @@ function quux () {
23242531
*/
23252532
const quux = () => foo;
23262533

2327-
/**
2534+
/**
23282535
* @returns {Promise<void>}
23292536
*/
23302537
async function quux() {}
23312538

2332-
/**
2539+
/**
23332540
* @returns {Promise<void>}
23342541
*/
23352542
async () => {}
2543+
2544+
/**
2545+
* @returns Foo.
2546+
* @abstract
2547+
*/
2548+
function quux () {
2549+
throw new Error('must be implemented by subclass!');
2550+
}
23362551
````
23372552

23382553

0 commit comments

Comments
 (0)