Skip to content

Commit c7726bb

Browse files
tmcwtmcw
authored
Report bad TOC entries. Fixes #442 (#475)
1 parent 211a260 commit c7726bb

File tree

9 files changed

+91
-48
lines changed

9 files changed

+91
-48
lines changed

‎index.js

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ function expandInputs(indexes, options, callback) {
9797
*
9898
* });
9999
*/
100-
module.exports.build = function (indexes, options, callback) {
100+
function build(indexes, options, callback) {
101101
options = options || {};
102102

103103
if (typeof indexes === 'string') {
@@ -114,7 +114,8 @@ module.exports.build = function (indexes, options, callback) {
114114
callback(e);
115115
}
116116
});
117-
};
117+
}
118+
118119

119120
/**
120121
* Generate JavaScript documentation given a list of inputs. This internal
@@ -244,6 +245,7 @@ module.exports.lint = function lint(indexes, options, callback) {
244245

245246
module.exports.expandInputs = expandInputs;
246247
module.exports.buildSync = buildSync;
248+
module.exports.build = build;
247249

248250
/**
249251
* Documentation's formats are modular methods that take comments

‎lib/filter_access.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ function filterAccess(levels, comments) {
1515
levels = levels || ['public', 'undefined', 'protected'];
1616

1717
function filter(comment) {
18-
return !comment.ignore && levels.indexOf(String(comment.access)) !== -1;
18+
return comment.kind === 'note' ||
19+
(!comment.ignore && levels.indexOf(String(comment.access)) !== -1);
1920
}
2021

2122
function recurse(comment) {

‎lib/output/json.js

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ module.exports = function (comments, opts, callback) {
2626

2727
walk(comments, function (comment) {
2828
delete comment.errors;
29-
delete comment.context.sortKey;
29+
if (comment.context) {
30+
delete comment.context.sortKey;
31+
}
3032
});
3133

3234
return callback(null, JSON.stringify(comments, null, 2));

‎lib/sort.js

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
'use strict';
22

33
var parseMarkdown = require('./parse_markdown');
4+
var chalk = require('chalk');
45

56
/**
67
* Sort two documentation objects, given an optional order object. Returns
@@ -25,7 +26,15 @@ module.exports = function sortDocs(comments, options) {
2526
memo[val] = i;
2627
}
2728
return memo;
28-
}, {});
29+
}, Object.create(null));
30+
var toBeSorted = options.toc.reduce(function (memo, val) {
31+
if (typeof val === 'string') {
32+
memo[val] = false;
33+
}
34+
return memo;
35+
}, Object.create(null));
36+
// Table of contents 'theme' entries: defined as objects
37+
// in the YAML list
2938
var fixed = options.toc.filter(function (val) {
3039
return typeof val === 'object' && val.name;
3140
}).map(function (val) {
@@ -48,6 +57,7 @@ module.exports = function sortDocs(comments, options) {
4857
// to-be-sorted list.
4958
if (!comment.memberof && indexes[comment.name] !== undefined) {
5059
fixed.push(comment);
60+
toBeSorted[comment.name] = true;
5161
} else {
5262
unfixed.push(comment);
5363
}
@@ -60,5 +70,11 @@ module.exports = function sortDocs(comments, options) {
6070
unfixed.sort(function (a, b) {
6171
return a.context.sortKey.localeCompare(b.context.sortKey);
6272
});
73+
Object.keys(toBeSorted).filter(function (key) {
74+
return toBeSorted[key] === false;
75+
}).forEach(function (key) {
76+
process.stderr.write(chalk.red('Table of contents defined sorting of ' + key +
77+
' but no documentation with that namepath was found\n'));
78+
});
6379
return fixed.concat(unfixed);
6480
};

‎test/bin.js

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,25 @@ test('accepts config file', function (t) {
102102
});
103103
}, options);
104104

105+
test('accepts config file - reports failures', function (t) {
106+
documentation(['build fixture/sorting/input.js -c fixture/config-bad.yml'], {},
107+
function (err, data, stderr) {
108+
t.error(err);
109+
if (process.env.UPDATE) {
110+
fs.writeFileSync(
111+
path.resolve(__dirname,
112+
'fixture',
113+
'sorting/output-bad.txt'), stderr, 'utf8');
114+
}
115+
var expected = fs.readFileSync(
116+
path.resolve(__dirname,
117+
'fixture',
118+
'sorting/output-bad.txt'), 'utf8');
119+
t.equal(stderr, expected, 'reported a missing toc entry');
120+
t.end();
121+
}, false);
122+
}, options);
123+
105124
test('--shallow option', function (t) {
106125
documentation(['build --shallow fixture/internal.input.js'], function (err, data) {
107126
t.error(err);

‎test/fixture/config-bad.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
toc:
2+
- notfound

‎test/fixture/config.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"order": ["bananas", "carrots", "apples"]
2+
"toc": ["bananas", "carrots", "apples"]
33
}

‎test/fixture/sorting/output-bad.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Table of contents defined sorting of notfound but no documentation with that namepath was found

‎test/fixture/sorting/output.json

Lines changed: 42 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"children": [
99
{
1010
"type": "text",
11-
"value": "Apples are red",
11+
"value": "Bananas are yellow",
1212
"position": {
1313
"start": {
1414
"line": 1,
@@ -17,8 +17,8 @@
1717
},
1818
"end": {
1919
"line": 1,
20-
"column": 15,
21-
"offset": 14
20+
"column": 19,
21+
"offset": 18
2222
},
2323
"indent": []
2424
}
@@ -32,8 +32,8 @@
3232
},
3333
"end": {
3434
"line": 1,
35-
"column": 15,
36-
"offset": 14
35+
"column": 19,
36+
"offset": 18
3737
},
3838
"indent": []
3939
}
@@ -47,49 +47,49 @@
4747
},
4848
"end": {
4949
"line": 1,
50-
"column": 15,
51-
"offset": 14
50+
"column": 19,
51+
"offset": 18
5252
}
5353
}
5454
},
5555
"tags": [],
5656
"loc": {
5757
"start": {
58-
"line": 1,
58+
"line": 8,
5959
"column": 0
6060
},
6161
"end": {
62-
"line": 3,
62+
"line": 10,
6363
"column": 3
6464
}
6565
},
6666
"context": {
6767
"loc": {
6868
"start": {
69-
"line": 4,
69+
"line": 11,
7070
"column": 0
7171
},
7272
"end": {
73-
"line": 6,
73+
"line": 13,
7474
"column": 2
7575
}
7676
},
7777
"file": "[path]",
7878
"code": "/**\n * Apples are red\n */\nvar apples = function() {\n return 'red';\n};\n\n/**\n * Bananas are yellow\n */\nvar bananas = function() {\n return 'yellow';\n};\n\n/**\n * Carrots are awesome\n */\nvar carrots = function() {\n return 'awesome';\n};\n"
7979
},
80-
"name": "apples",
80+
"name": "bananas",
8181
"kind": "function",
8282
"members": {
8383
"instance": [],
8484
"static": []
8585
},
8686
"path": [
8787
{
88-
"name": "apples",
88+
"name": "bananas",
8989
"kind": "function"
9090
}
9191
],
92-
"namespace": "apples"
92+
"namespace": "bananas"
9393
},
9494
{
9595
"description": {
@@ -100,7 +100,7 @@
100100
"children": [
101101
{
102102
"type": "text",
103-
"value": "Bananas are yellow",
103+
"value": "Carrots are awesome",
104104
"position": {
105105
"start": {
106106
"line": 1,
@@ -109,8 +109,8 @@
109109
},
110110
"end": {
111111
"line": 1,
112-
"column": 19,
113-
"offset": 18
112+
"column": 20,
113+
"offset": 19
114114
},
115115
"indent": []
116116
}
@@ -124,8 +124,8 @@
124124
},
125125
"end": {
126126
"line": 1,
127-
"column": 19,
128-
"offset": 18
127+
"column": 20,
128+
"offset": 19
129129
},
130130
"indent": []
131131
}
@@ -139,49 +139,49 @@
139139
},
140140
"end": {
141141
"line": 1,
142-
"column": 19,
143-
"offset": 18
142+
"column": 20,
143+
"offset": 19
144144
}
145145
}
146146
},
147147
"tags": [],
148148
"loc": {
149149
"start": {
150-
"line": 8,
150+
"line": 15,
151151
"column": 0
152152
},
153153
"end": {
154-
"line": 10,
154+
"line": 17,
155155
"column": 3
156156
}
157157
},
158158
"context": {
159159
"loc": {
160160
"start": {
161-
"line": 11,
161+
"line": 18,
162162
"column": 0
163163
},
164164
"end": {
165-
"line": 13,
165+
"line": 20,
166166
"column": 2
167167
}
168168
},
169169
"file": "[path]",
170170
"code": "/**\n * Apples are red\n */\nvar apples = function() {\n return 'red';\n};\n\n/**\n * Bananas are yellow\n */\nvar bananas = function() {\n return 'yellow';\n};\n\n/**\n * Carrots are awesome\n */\nvar carrots = function() {\n return 'awesome';\n};\n"
171171
},
172-
"name": "bananas",
172+
"name": "carrots",
173173
"kind": "function",
174174
"members": {
175175
"instance": [],
176176
"static": []
177177
},
178178
"path": [
179179
{
180-
"name": "bananas",
180+
"name": "carrots",
181181
"kind": "function"
182182
}
183183
],
184-
"namespace": "bananas"
184+
"namespace": "carrots"
185185
},
186186
{
187187
"description": {
@@ -192,7 +192,7 @@
192192
"children": [
193193
{
194194
"type": "text",
195-
"value": "Carrots are awesome",
195+
"value": "Apples are red",
196196
"position": {
197197
"start": {
198198
"line": 1,
@@ -201,8 +201,8 @@
201201
},
202202
"end": {
203203
"line": 1,
204-
"column": 20,
205-
"offset": 19
204+
"column": 15,
205+
"offset": 14
206206
},
207207
"indent": []
208208
}
@@ -216,8 +216,8 @@
216216
},
217217
"end": {
218218
"line": 1,
219-
"column": 20,
220-
"offset": 19
219+
"column": 15,
220+
"offset": 14
221221
},
222222
"indent": []
223223
}
@@ -231,48 +231,48 @@
231231
},
232232
"end": {
233233
"line": 1,
234-
"column": 20,
235-
"offset": 19
234+
"column": 15,
235+
"offset": 14
236236
}
237237
}
238238
},
239239
"tags": [],
240240
"loc": {
241241
"start": {
242-
"line": 15,
242+
"line": 1,
243243
"column": 0
244244
},
245245
"end": {
246-
"line": 17,
246+
"line": 3,
247247
"column": 3
248248
}
249249
},
250250
"context": {
251251
"loc": {
252252
"start": {
253-
"line": 18,
253+
"line": 4,
254254
"column": 0
255255
},
256256
"end": {
257-
"line": 20,
257+
"line": 6,
258258
"column": 2
259259
}
260260
},
261261
"file": "[path]",
262262
"code": "/**\n * Apples are red\n */\nvar apples = function() {\n return 'red';\n};\n\n/**\n * Bananas are yellow\n */\nvar bananas = function() {\n return 'yellow';\n};\n\n/**\n * Carrots are awesome\n */\nvar carrots = function() {\n return 'awesome';\n};\n"
263263
},
264-
"name": "carrots",
264+
"name": "apples",
265265
"kind": "function",
266266
"members": {
267267
"instance": [],
268268
"static": []
269269
},
270270
"path": [
271271
{
272-
"name": "carrots",
272+
"name": "apples",
273273
"kind": "function"
274274
}
275275
],
276-
"namespace": "carrots"
276+
"namespace": "apples"
277277
}
278278
]

0 commit comments

Comments
 (0)