Skip to content

Commit 852352a

Browse files
gajusgajus
committed
Include options and error messages in the documentation examples.
1 parent 0a0c7b0 commit 852352a

File tree

2 files changed

+66
-24
lines changed

2 files changed

+66
-24
lines changed

‎README.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,27 +136,31 @@ The following patterns are considered problems:
136136
function quux (foo = 'FOO') {
137137

138138
}
139+
// Message: Expected @param names to be "foo". Got "Foo".
139140

140141
/**
141142
* @arg Foo
142143
*/
143144
function quux (foo = 'FOO') {
144145

145146
}
147+
// Message: Expected @arg names to be "foo". Got "Foo".
146148

147149
/**
148150
* @param Foo
149151
*/
150152
function quux (foo) {
151153

152154
}
155+
// Message: Expected @param names to be "foo". Got "Foo".
153156

154157
/**
155158
* @param Foo.Bar
156159
*/
157160
function quux (foo) {
158161

159162
}
163+
// Message: @param path declaration ("Foo.Bar") appears before any real parameter.
160164

161165
/**
162166
* @param foo
@@ -165,6 +169,7 @@ function quux (foo) {
165169
function quux (foo) {
166170

167171
}
172+
// Message: @param path declaration ("Foo.Bar") root node name ("Foo") does not match previous real parameter name ("foo").
168173

169174
/**
170175
* @param foo
@@ -174,6 +179,7 @@ function quux (foo) {
174179
function quux (bar, foo) {
175180

176181
}
182+
// Message: Expected @param names to be "bar, foo". Got "foo, bar".
177183

178184
/**
179185
* @param foo
@@ -182,6 +188,7 @@ function quux (bar, foo) {
182188
function quux (foo) {
183189

184190
}
191+
// Message: @param "bar" does not match an existing function parameter.
185192
```
186193

187194
The following patterns are not considered problems:
@@ -345,27 +352,31 @@ The following patterns are considered problems:
345352
function quux () {
346353

347354
}
355+
// Message: Invalid JSDoc tag name "Param".
348356

349357
/**
350358
* @foo
351359
*/
352360
function quux () {
353361

354362
}
363+
// Message: Invalid JSDoc tag name "foo".
355364

356365
/**
357366
* @arg foo
358367
*/
359368
function quux (foo) {
360369

361370
}
371+
// Message: Invalid JSDoc tag (preference). Replace "arg" JSDoc tag with "param".
362372

363373
/**
364374
* @param foo
365375
*/
366376
function quux (foo) {
367377

368378
}
379+
// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "arg".
369380
```
370381

371382
The following patterns are not considered problems:
@@ -417,13 +428,15 @@ The following patterns are considered problems:
417428
function quux (foo) {
418429

419430
}
431+
// Message: Invalid JSDoc @param "foo" type "Number".
420432

421433
/**
422434
* @arg {Number} foo
423435
*/
424436
function quux (foo) {
425437

426438
}
439+
// Message: Invalid JSDoc @arg "foo" type "Number".
427440
```
428441

429442
The following patterns are not considered problems:
@@ -463,6 +476,7 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
463476
The following patterns are considered problems:
464477

465478
```js
479+
// Options: ["always"]
466480
/**
467481
* Foo.
468482
*
@@ -472,7 +486,9 @@ The following patterns are considered problems:
472486
function quux () {
473487

474488
}
489+
// Message: There must be a newline after the description of the JSDoc block.
475490

491+
// Options: ["never"]
476492
/**
477493
* Bar.
478494
*
@@ -483,25 +499,29 @@ function quux () {
483499
function quux () {
484500

485501
}
502+
// Message: There must be no newline after the description of the JSDoc block.
486503
```
487504

488505
The following patterns are not considered problems:
489506

490507
```js
508+
// Options: ["always"]
491509
/**
492510
* Foo.
493511
*/
494512
function quux () {
495513

496514
}
497515

516+
// Options: ["never"]
498517
/**
499518
* Bar.
500519
*/
501520
function quux () {
502521

503522
}
504523

524+
// Options: ["always"]
505525
/**
506526
* Foo.
507527
*
@@ -511,6 +531,7 @@ function quux () {
511531

512532
}
513533

534+
// Options: ["never"]
514535
/**
515536
* Bar.
516537
* @bar
@@ -544,6 +565,7 @@ The following patterns are considered problems:
544565
function quux () {
545566

546567
}
568+
// Message: Description must start with an uppercase character.
547569

548570
/**
549571
* Foo.
@@ -553,13 +575,15 @@ function quux () {
553575
function quux () {
554576

555577
}
578+
// Message: Paragraph must start with an uppercase character.
556579

557580
/**
558581
* Foo
559582
*/
560583
function quux () {
561584

562585
}
586+
// Message: Sentence must end with a period.
563587

564588
/**
565589
* Foo
@@ -568,6 +592,7 @@ function quux () {
568592
function quux () {
569593

570594
}
595+
// Message: A line of text is started with an uppercase character, but preceding line does not end the sentence.
571596

572597
/**
573598
* Foo.
@@ -577,6 +602,7 @@ function quux () {
577602
function quux (foo) {
578603

579604
}
605+
// Message: Description must start with an uppercase character.
580606

581607
/**
582608
* Foo.
@@ -586,6 +612,7 @@ function quux (foo) {
586612
function quux (foo) {
587613

588614
}
615+
// Message: Description must start with an uppercase character.
589616
```
590617

591618
The following patterns are not considered problems:
@@ -657,6 +684,7 @@ The following patterns are considered problems:
657684
function quux () {
658685

659686
}
687+
// Message: There must be a hyphen before @param description.
660688
```
661689

662690
The following patterns are not considered problems:
@@ -689,20 +717,23 @@ The following patterns are considered problems:
689717
function quux (foo) {
690718

691719
}
720+
// Message: Missing JSDoc @param "foo" declaration.
692721

693722
/**
694723
*
695724
*/
696725
function quux (foo) {
697726

698727
}
728+
// Message: Missing JSDoc @arg "foo" declaration.
699729

700730
/**
701731
* @param foo
702732
*/
703733
function quux (foo, bar) {
704734

705735
}
736+
// Message: Missing JSDoc @param "bar" declaration.
706737
```
707738

708739
The following patterns are not considered problems:
@@ -742,13 +773,15 @@ The following patterns are considered problems:
742773
function quux (foo) {
743774

744775
}
776+
// Message: Missing JSDoc @param "foo" description.
745777

746778
/**
747779
* @arg foo
748780
*/
749781
function quux (foo) {
750782

751783
}
784+
// Message: Missing JSDoc @arg "foo" description.
752785
```
753786

754787
The following patterns are not considered problems:
@@ -788,13 +821,15 @@ The following patterns are considered problems:
788821
function quux (foo) {
789822

790823
}
824+
// Message: Missing JSDoc @param "foo" type.
791825

792826
/**
793827
* @arg foo
794828
*/
795829
function quux (foo) {
796830

797831
}
832+
// Message: Missing JSDoc @arg "foo" type.
798833
```
799834

800835
The following patterns are not considered problems:
@@ -834,13 +869,15 @@ The following patterns are considered problems:
834869
function quux (foo) {
835870

836871
}
872+
// Message: Missing JSDoc @returns description.
837873

838874
/**
839875
* @return
840876
*/
841877
function quux (foo) {
842878

843879
}
880+
// Message: Missing JSDoc @return description.
844881
```
845882

846883
The following patterns are not considered problems:
@@ -880,20 +917,23 @@ The following patterns are considered problems:
880917
function quux () {
881918

882919
}
920+
// Message: Missing JSDoc @returns type.
883921

884922
/**
885923
* @returns Foo.
886924
*/
887925
function quux () {
888926

889927
}
928+
// Message: Missing JSDoc @returns type.
890929

891930
/**
892931
* @return Foo.
893932
*/
894933
function quux () {
895934

896935
}
936+
// Message: Missing JSDoc @return type.
897937
```
898938

899939
The following patterns are not considered problems:

‎bin/readme-assertions.js

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,41 +6,46 @@ import glob from 'glob';
66
import path from 'path';
77
import fs from 'fs';
88

9-
let getAssertions,
10-
updateDocuments,
11-
trimCode;
9+
const formatCodeSnippet = (setup) => {
10+
const paragraphs = [];
1211

13-
getAssertions = () => {
14-
let assertionFiles,
15-
assertionNames,
16-
assertionCodes;
12+
if (setup.options) {
13+
paragraphs.push('// Options: ' + JSON.stringify(setup.options));
14+
}
1715

18-
assertionFiles = glob.sync(path.resolve(__dirname, './../tests/rules/assertions/*.js'));
16+
paragraphs.push(trimCode(setup.code));
1917

20-
assertionNames = _.map(assertionFiles, (filePath) => {
18+
if (setup.errors) {
19+
paragraphs.push('// Message: ' + setup.errors[0].message);
20+
}
21+
22+
return paragraphs.join('\n');
23+
};
24+
25+
const getAssertions = () => {
26+
const assertionFiles = glob.sync(path.resolve(__dirname, './../tests/rules/assertions/*.js'));
27+
28+
const assertionNames = _.map(assertionFiles, (filePath) => {
2129
return path.basename(filePath, '.js');
2230
});
2331

24-
assertionCodes = _.map(assertionFiles, (filePath) => {
32+
const assertionCodes = _.map(assertionFiles, (filePath) => {
2533
let codes;
2634

2735
codes = require(filePath).default;
2836

2937
return {
30-
valid: _.map(_.map(codes.valid, 'code'), trimCode),
31-
invalid: _.map(_.map(codes.invalid, 'code'), trimCode)
38+
valid: _.map(codes.valid, formatCodeSnippet),
39+
invalid: _.map(codes.invalid, formatCodeSnippet)
3240
};
3341
});
3442

3543
return _.zipObject(assertionNames, assertionCodes);
3644
};
3745

38-
trimCode = (code) => {
39-
let lines,
40-
indentSize;
41-
42-
lines = _.trim(code).split('\n');
43-
indentSize = lines[lines.length - 1].match(/^\s+/)[0].length;
46+
const trimCode = (code) => {
47+
let lines = _.trim(code).split('\n');
48+
const indentSize = lines[lines.length - 1].match(/^\s+/)[0].length;
4449

4550
lines = _.map(lines, (line, i) => {
4651
if (i === 0) {
@@ -53,13 +58,10 @@ trimCode = (code) => {
5358
return lines.join('\n');
5459
};
5560

56-
updateDocuments = (assertions) => {
57-
let documentBody,
58-
readmeDocumentPath;
59-
60-
readmeDocumentPath = path.join(__dirname, './../README.md');
61+
const updateDocuments = (assertions) => {
62+
const readmeDocumentPath = path.join(__dirname, './../README.md');
6163

62-
documentBody = fs.readFileSync(readmeDocumentPath, 'utf8');
64+
let documentBody = fs.readFileSync(readmeDocumentPath, 'utf8');
6365

6466
documentBody = documentBody.replace(/<!-- assertions ([a-z]+?) -->/ig, (assertionsBlock) => {
6567
let ruleName,

0 commit comments

Comments
 (0)