Skip to content

Commit b30413f

Browse files
kgrytekgryte
committed
Add JSDoc json template
1 parent f977924 commit b30413f

17 files changed

Lines changed: 727 additions & 0 deletions

File tree

‎tools/docs/jsdoc/templates/json/publish.js‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
'use strict';
2+
3+
// MODULES //
4+
5+
var transform = require( './transform.js' );
6+
7+
8+
// VARIABLES //
9+
10+
var opts = {
11+
'undocumented': true
12+
};
13+
14+
15+
// PUBLISH //
16+
17+
/**
18+
* Transforms an array of raw `doclet` objects and writes to `stdout`.
19+
*
20+
* @param {TAFFY} data - TAFFY database
21+
* @returns {Void}
22+
*/
23+
function publish( data ) {
24+
var root;
25+
var docs;
26+
27+
// Remove undocumented doclets:
28+
data( opts ).remove();
29+
30+
// Retrieve an array of raw doclet objects:
31+
docs = data().get();
32+
33+
// Transform the raw doclet array:
34+
root = {};
35+
transform( root, docs );
36+
37+
// Write to stdout:
38+
console.log( JSON.stringify( root ) );
39+
} // end FUNCTION publish()
40+
41+
42+
// EXPORTS //
43+
44+
module.exports = {};
45+
module.exports.publish = publish;

‎tools/docs/jsdoc/templates/json/transform.js‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
'use strict';
2+
3+
// MODULES //
4+
5+
var transforms = require( './transforms' );
6+
7+
8+
// VARIABLES //
9+
10+
var map = {
11+
'namespace': 'namespaces',
12+
'mixin': 'mixins',
13+
'function': 'functions',
14+
'member': 'properties',
15+
'event': 'events',
16+
'class': 'classes'
17+
};
18+
19+
var recurse = {
20+
'namespace': true,
21+
'mixin': true,
22+
'function': false,
23+
'member': true,
24+
'event': false,
25+
'class': true
26+
};
27+
28+
29+
// TRANSFORM //
30+
31+
/**
32+
* Recursively transforms doclet nodes.
33+
*
34+
* @param {Object} parentNode - parent doclet node
35+
* @param {Object[]} childNodes - array of child nodes
36+
* @param {String} parentLongName - long form of a parent name
37+
* @returns {Void}
38+
*/
39+
function transform( parentNode, childNodes, parentLongname ) {
40+
var node;
41+
var tmp;
42+
var key;
43+
var out;
44+
var fcn;
45+
var i;
46+
47+
// Filter for child nodes...
48+
tmp = [];
49+
for ( i = 0; i < childNodes.length; i++ ) {
50+
if ( childNodes[ i ].memberof === parentLongname ) {
51+
tmp.push( childNodes[ i ] );
52+
}
53+
}
54+
childNodes = tmp;
55+
if ( childNodes.length === 0 ) {
56+
return;
57+
}
58+
// For each child node, apply a transformation...
59+
for ( i = 0; i < childNodes.length; i++ ) {
60+
node = childNodes[ i ];
61+
62+
// Apply a transform...
63+
fcn = transforms[ node.kind ];
64+
if ( fcn === void 0 ) {
65+
continue;
66+
}
67+
out = fcn( node );
68+
69+
// Cache the transformed node...
70+
key = map[ node.kind ];
71+
tmp = parentNode[ key ];
72+
if ( tmp === void 0 ) {
73+
tmp = [];
74+
parentNode[ key ] = tmp;
75+
}
76+
tmp.push( out );
77+
78+
// Check if we need to recurse...
79+
if ( recurse[ node.kind ] ) {
80+
transform( out, childNodes, node.longname );
81+
}
82+
}
83+
} // end FUNCTION transform()
84+
85+
86+
// EXPORTS //
87+
88+
module.exports = transform;

‎tools/docs/jsdoc/templates/json/transforms/class/examples.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
'use strict';
2+
3+
/**
4+
* Transforms `examples` doclet elements.
5+
*
6+
* @param {Object[]} nodes - doclet elements
7+
* @returns {Object[]} filtered objects
8+
*/
9+
function transform( nodes ) {
10+
var out;
11+
var i;
12+
out = new Array( nodes.length );
13+
for ( i = 0; i < nodes.length; i++ ) {
14+
out[ i ] = nodes[ i ];
15+
}
16+
return out;
17+
} // end FUNCTION transform()
18+
19+
20+
// EXPORTS //
21+
22+
module.exports = transform;

‎tools/docs/jsdoc/templates/json/transforms/class/index.js‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
'use strict';
2+
3+
// MODULES //
4+
5+
var transformExamples = require( './examples.js' );
6+
var transformParams = require( './params.js' );
7+
8+
9+
// TRANSFORM //
10+
11+
/**
12+
* Transforms a `event` doclet element.
13+
*
14+
* @param {Object} node - doclet element
15+
* @returns {Object} filtered object
16+
*/
17+
function transform( node ) {
18+
var out;
19+
out = {
20+
'name': node.name,
21+
'description': node.description || '',
22+
'extends': node.augments || [],
23+
'fires': node.fires || '',
24+
'constructor': {
25+
'name': node.name,
26+
'description': node.description
27+
},
28+
'access': node.access || '',
29+
'virtual': !!node.virtual
30+
};
31+
if ( node.examples ) {
32+
out.constructor.examples = transformExamples( node.examples );
33+
} else {
34+
out.constructor.examples = [];
35+
}
36+
if ( node.params ) {
37+
out.constructor.parameters = transformParams( node.params );
38+
} else {
39+
out.constructor.parameters = [];
40+
}
41+
return out;
42+
} // end FUNCTION transform()
43+
44+
45+
// EXPORTS //
46+
47+
module.exports = transform;

‎tools/docs/jsdoc/templates/json/transforms/class/params.js‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
'use strict';
2+
3+
// FUNCTIONS //
4+
5+
var hasOwn = Object.prototype.hasOwnProperty;
6+
7+
/**
8+
* Filters a `params` doclet element.
9+
*
10+
* @private
11+
* @param {Object} node - doclet element
12+
* @returns {Object} filtered object
13+
*/
14+
function filter( node ) {
15+
var isNullable;
16+
var isOptional;
17+
var type;
18+
var desc;
19+
var val;
20+
21+
if ( node.type ) {
22+
if ( node.type.names.length === 1 ) {
23+
type = node.type.names[ 0 ];
24+
} else {
25+
type = node.type.names;
26+
}
27+
} else {
28+
type = '';
29+
}
30+
desc = node.description || '';
31+
if ( hasOwn.call( node, 'defaultvalue' ) ) {
32+
val = node.defaultvalue;
33+
} else {
34+
val = '';
35+
}
36+
if ( typeof node.optional === 'boolean' ) {
37+
isOptional = node.optional;
38+
} else {
39+
isOptional = '';
40+
}
41+
if ( typeof node.nullable === 'boolean' ) {
42+
isNullable = node.nullable;
43+
} else {
44+
isNullable = '';
45+
}
46+
return {
47+
'name': node.name,
48+
'type': type,
49+
'description': desc,
50+
'default': val,
51+
'optional': isOptional,
52+
'nullable': isNullable
53+
};
54+
} // end FUNCTION filter()
55+
56+
57+
// TRANSFORM //
58+
59+
/**
60+
* Transforms `params` doclet elements.
61+
*
62+
* @param {Object[]} nodes - doclet elements
63+
* @returns {Object[]} filtered objects
64+
*/
65+
function transform( nodes ) {
66+
var out;
67+
var i;
68+
69+
out = new Array( nodes.length );
70+
for ( i = 0; i < nodes.length; i++ ) {
71+
out[ i ] = filter( nodes[ i ] );
72+
}
73+
return out;
74+
} // end FUNCTION transform()
75+
76+
77+
// EXPORTS //
78+
79+
module.exports = transform;

‎tools/docs/jsdoc/templates/json/transforms/event/examples.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
'use strict';
2+
3+
/**
4+
* Transforms `examples` doclet elements.
5+
*
6+
* @param {Object[]} nodes - doclet elements
7+
* @returns {Object[]} filtered objects
8+
*/
9+
function transform( nodes ) {
10+
var out;
11+
var i;
12+
out = new Array( nodes.length );
13+
for ( i = 0; i < nodes.length; i++ ) {
14+
out[ i ] = nodes[ i ];
15+
}
16+
return out;
17+
} // end FUNCTION transform()
18+
19+
20+
// EXPORTS //
21+
22+
module.exports = transform;

‎tools/docs/jsdoc/templates/json/transforms/event/index.js‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
'use strict';
2+
3+
// MODULES //
4+
5+
var transformReturns = require( './returns.js' );
6+
var transformExamples = require( './examples.js' );
7+
var transformParams = require( './params.js' );
8+
9+
10+
// TRANSFORM //
11+
12+
/**
13+
* Transforms a `event` doclet element.
14+
*
15+
* @param {Object} node - doclet element
16+
* @returns {Object} filtered object
17+
*/
18+
function transform( node ) {
19+
var out;
20+
21+
out = {
22+
'name': node.name,
23+
'description': node.description || '',
24+
'access': node.access || '',
25+
'virtual': !!node.virtual
26+
};
27+
if ( node.returns ) {
28+
out.returns = transformReturns( node.returns );
29+
}
30+
if ( node.examples ) {
31+
out.examples = transformExamples( node.examples );
32+
} else {
33+
out.examples = [];
34+
}
35+
if ( node.params ) {
36+
out.parameters = transformParams( node.params );
37+
} else {
38+
out.parameters = [];
39+
}
40+
return out;
41+
} // end FUNCTION transform()
42+
43+
44+
// EXPORTS //
45+
46+
module.exports = transform;

0 commit comments

Comments
 (0)