Skip to content

Commit 8b68d80

Browse files
75lb75lb
committed
support for jsdoc's separate data format for ES 2015 classes. Fixes #16.
1 parent d4e6499 commit 8b68d80

7 files changed

Lines changed: 157 additions & 100 deletions

File tree

‎lib/cli-options.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ exports.definitions = [
2424
name: 'conf',
2525
type: String,
2626
typeLabel: '[underline]{file}',
27-
description: 'Jsdoc config file.'
27+
description: 'Path to a jsdoc configuration file, passed directly to `jsdoc -c`.'
2828
},
2929
{
3030
name: 'sort-by',

‎lib/publish.js‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,13 @@ This is a jsdoc plugin. It transforms jsdoc format data to the preferred jsdoc-p
1010
*/
1111
exports.publish = function (data) {
1212
var query = { '!undocumented': true, '!kind': /package|file/ }
13-
var json = a.where(data().get(), query)
13+
let json = data().get().filter(i => {
14+
if (i.kind === 'class') {
15+
return true
16+
} else {
17+
return !i.undocumented && !/package|file/.test(i.kind)
18+
}
19+
})
1420

1521
json = json.map(transform.setIsExportedFlag)
1622
json = json.map(transform.setCodename)

‎lib/transform.js‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,12 @@ function setID (identifier) {
3737
identifier.id = identifier.longname
3838
}
3939
if (identifier.kind === 'constructor') {
40-
identifier.id = identifier.longname + '()'
40+
if (identifier.scope === 'static') {
41+
identifier.id = identifier.longname
42+
delete identifier.scope
43+
} else {
44+
identifier.id = identifier.longname + '()'
45+
}
4146
}
4247
if (identifier.isExported) {
4348
identifier.id = identifier.longname + '--' + identifier.codeName
@@ -101,10 +106,26 @@ function createConstructor (class_) {
101106
/* split each class found into two new items, then re-insert them over the original class */
102107
function insertConstructors (data) {
103108
var replacements = []
109+
var toDelete = []
104110

105111
data.forEach(function (identifier, index) {
106-
if (identifier.kind === 'class') {
107-
replacements.push({ index: index, items: createConstructor(identifier) })
112+
if (identifier.kind === 'class' && identifier.scope !== 'static') {
113+
const es6constructor = a.findWhere(data, { kind: 'class', scope: 'static', memberof: identifier.longname })
114+
if (es6constructor) {
115+
if (!(es6constructor.description || (es6constructor.params && es6constructor.params.length))) {
116+
toDelete.push(es6constructor)
117+
}
118+
es6constructor.kind = 'constructor'
119+
const constructorChildren = a.where(data, { memberof: es6constructor.longname })
120+
constructorChildren.forEach(i => {
121+
i.memberof = identifier.longname
122+
})
123+
identifier.description = identifier.classdesc
124+
delete identifier.classdesc
125+
delete identifier.params
126+
} else {
127+
replacements.push({ index: index, items: createConstructor(identifier) })
128+
}
108129
}
109130
})
110131

@@ -113,6 +134,10 @@ function insertConstructors (data) {
113134
data.splice.apply(data, spliceArgs)
114135
})
115136

137+
toDelete.forEach(d => {
138+
data.splice(data.indexOf(d), 1)
139+
})
140+
116141
return data
117142
}
118143

@@ -259,7 +284,7 @@ function sort (object, sortFunction) {
259284
}
260285

261286
function sortIdentifier (identifier) {
262-
var fieldOrder = [ 'id', 'longname', 'name', 'scope', 'kind', 'isExported', 'classdesc', 'augments', 'inherits', 'inherited', 'overrides', 'mixes', 'description', 'memberof', 'alias', 'params', 'fires', 'examples', 'returns', 'type', 'defaultvalue', 'readonly', 'thisvalue', 'isEnum', 'properties', 'optional', 'nullable', 'variable', 'author', 'deprecated', 'ignore', 'access', 'requires', 'version', 'since', 'licenses', 'license', 'typicalname', 'category', 'see', 'exceptions', 'codeName', 'todoList', 'customTags', 'chainable', 'order' ]
287+
var fieldOrder = [ 'id', 'longname', 'name', 'scope', 'kind', 'isExported', 'classdesc', 'augments', 'inherits', 'inherited', 'implements', 'overrides', 'mixes', 'description', 'memberof', 'alias', 'params', 'fires', 'examples', 'returns', 'type', 'defaultvalue', 'readonly', 'thisvalue', 'isEnum', 'properties', 'optional', 'nullable', 'variable', 'author', 'deprecated', 'ignore', 'access', 'requires', 'version', 'since', 'licenses', 'license', 'typicalname', 'category', 'see', 'exceptions', 'codeName', 'todoList', 'customTags', 'chainable', 'meta', 'order' ]
263288
return sort(identifier, function (a, b) {
264289
if (fieldOrder.indexOf(a) === -1 && fieldOrder.indexOf(b) > -1) {
265290
return 1

‎test/buggy/class-instance-es5.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/* class instance property docs not output if `@module` specified */
2+
3+
/**
4+
* @module something
5+
*/
6+
7+
/**
8+
* constructor description
9+
* @class
10+
* @classdesc create something
11+
*/
12+
function Something () {
13+
/**
14+
* a value
15+
* @type {number}
16+
*/
17+
this.whatever = 1
18+
}

‎test/buggy/class-instance.js‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,19 @@
88
* create something
99
*/
1010
class Something {
11+
/**
12+
* constructor description
13+
*/
1114
constructor () {
1215
/**
1316
* a value
1417
* @type {number}
1518
*/
1619
this.whatever = 1
1720
}
21+
22+
/**
23+
* one
24+
*/
25+
one () {}
1826
}

‎test/transforms/expected/createConstructor.json‎

Lines changed: 51 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,53 @@
11
[
2-
{
3-
"name": "module:file-set",
4-
"longname": "module:file-set",
5-
"alias": "module:file-set",
6-
"kind": "class",
7-
"description": "Expands file patterns, returning the matched and unmatched files and directories"
8-
},
9-
{
10-
"name": "module:file-set",
11-
"longname": "module:file-set",
12-
"memberof": "module:file-set",
13-
"kind": "constructor",
14-
"description": "constructor description",
15-
"params": [
16-
{
17-
"type": {
18-
"names": [
19-
"string",
20-
"Array.<string>"
21-
]
22-
},
23-
"optional": null,
24-
"nullable": null,
25-
"variable": null,
26-
"defaultvalue": null,
27-
"description": "A pattern, or array of patterns to expand",
28-
"name": "patternList"
29-
}
30-
],
31-
"returns": [
32-
{
33-
"type": {
34-
"names": [
35-
"string"
36-
]
37-
},
38-
"optional": null,
39-
"nullable": null,
40-
"variable": null,
41-
"defaultvalue": null
42-
}
43-
],
44-
"examples": [
45-
"var thisVar = funtion(){\n return \"a value\";\n};"
46-
],
47-
"exceptions": [
48-
{
49-
"description": "Invalid argument error if the argument cannot be converted to a finite numeric value."
50-
}
51-
]
52-
}
2+
{
3+
"name": "module:file-set",
4+
"longname": "module:file-set",
5+
"alias": "module:file-set",
6+
"kind": "class",
7+
"description": "Expands file patterns, returning the matched and unmatched files and directories"
8+
},
9+
{
10+
"name": "module:file-set",
11+
"longname": "module:file-set",
12+
"memberof": "module:file-set",
13+
"kind": "constructor",
14+
"description": "constructor description",
15+
"params": [
16+
{
17+
"type": {
18+
"names": [
19+
"string",
20+
"Array.<string>"
21+
]
22+
},
23+
"optional": null,
24+
"nullable": null,
25+
"variable": null,
26+
"defaultvalue": null,
27+
"description": "A pattern, or array of patterns to expand",
28+
"name": "patternList"
29+
}
30+
],
31+
"returns": [
32+
{
33+
"type": {
34+
"names": [
35+
"string"
36+
]
37+
},
38+
"optional": null,
39+
"nullable": null,
40+
"variable": null,
41+
"defaultvalue": null
42+
}
43+
],
44+
"examples": [
45+
"var thisVar = funtion(){\n return \"a value\";\n};"
46+
],
47+
"exceptions": [
48+
{
49+
"description": "Invalid argument error if the argument cannot be converted to a finite numeric value."
50+
}
51+
]
52+
}
5353
]

‎test/transforms/fixture/createConstructor.json‎

Lines changed: 43 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,45 @@
11
{
2-
"name": "module:file-set",
3-
"longname": "module:file-set",
4-
"alias": "module:file-set",
5-
"kind": "class",
6-
"description": "constructor description",
7-
"classdesc": "Expands file patterns, returning the matched and unmatched files and directories",
8-
"params": [
9-
{
10-
"type": {
11-
"names": [
12-
"string",
13-
"Array.<string>"
14-
]
15-
},
16-
"optional": null,
17-
"nullable": null,
18-
"variable": null,
19-
"defaultvalue": null,
20-
"description": "A pattern, or array of patterns to expand",
21-
"name": "patternList"
22-
}
23-
],
24-
"returns": [
25-
{
26-
"type": {
27-
"names": [
28-
"string"
29-
]
30-
},
31-
"optional": null,
32-
"nullable": null,
33-
"variable": null,
34-
"defaultvalue": null
35-
}
36-
],
37-
"examples": [
38-
"var thisVar = funtion(){\n return \"a value\";\n};"
39-
],
40-
"exceptions": [
41-
{
42-
"description": "Invalid argument error if the argument cannot be converted to a finite numeric value."
43-
}
44-
]
2+
"name": "module:file-set",
3+
"longname": "module:file-set",
4+
"alias": "module:file-set",
5+
"kind": "class",
6+
"description": "constructor description",
7+
"classdesc": "Expands file patterns, returning the matched and unmatched files and directories",
8+
"params": [
9+
{
10+
"type": {
11+
"names": [
12+
"string",
13+
"Array.<string>"
14+
]
15+
},
16+
"optional": null,
17+
"nullable": null,
18+
"variable": null,
19+
"defaultvalue": null,
20+
"description": "A pattern, or array of patterns to expand",
21+
"name": "patternList"
22+
}
23+
],
24+
"returns": [
25+
{
26+
"type": {
27+
"names": [
28+
"string"
29+
]
30+
},
31+
"optional": null,
32+
"nullable": null,
33+
"variable": null,
34+
"defaultvalue": null
35+
}
36+
],
37+
"examples": [
38+
"var thisVar = funtion(){\n return \"a value\";\n};"
39+
],
40+
"exceptions": [
41+
{
42+
"description": "Invalid argument error if the argument cannot be converted to a finite numeric value."
43+
}
44+
]
4545
}

0 commit comments

Comments
 (0)