Cocos2d-JS jsdoc
Target
Write well formatted comment && Generate a pretty online document for cocos2d-js
game project.
Related Skills
javascript
node.js
python
html
css
jsdoc && cocos2d-js Comment Specification
jsdoc
Installation
jsdoc
User Guide
cocos2d-js
Extended Custom Class
/** * @class * @extends cc.Node * @property {Number} a - property a of cc.CustomNode * @property {Number} b - property b of cc.CustomNode * @property {Number} c - property c of cc.CustomNode * @classdesc cc.CustomNode */ cc.CustomNode = cc.Node.extend(/** @lends cc.CustomNode# */{ // ...... });
Custom Class Instance Method
cc.CustomNode = cc.Node.extend(/** @lends cc.CustomNode# */{ /** * cocos constructor * @function */ ctor:function() { cc.Node.prototype.ctor.call(this); }, /** * cc.CustomNode instance Method A * @function */ funcA:function() {}, /** * cc.CustomNode instance Method B * @function */ funcB:function() {} });
Custom Class Static Method
cc.CustomNode = cc.Node.extend(/** @lends cc.CustomNode# */{ // ...... }); /** * cc.CustomNode Class Static Method * @return {cc.CustomNode} * @example * // example * var node = cc.CustomNode.create(); */ cc.CustomNode.create = function() {};
Namespace
/** * cc Namespace. * @namespace */ var cc = cc || {}; /** * cc.NamespaceA Namespace. * @namespace */ cc.NamespaceA = cc.NamespaceA || {}; /** * cc.NamespaceB Namespace. * @namespace */ cc.NamespaceB = cc.NamespaceB || {};
Namespace && Global Variable
/** * Global Custom Tag * @constant * @type Number */ cc.CUSTOM_TAG = 99999;
Namespace && Static Method
/** * SomeUtil -- A static util function. * @param {int} param1 - param1 * @param {int} param2 - param2 * @param {int} param3 - param3 * @return {int} */ cc.NamespaceA.SomeUtil = function (param1, param2, param3) { return param1 + param2 + param3; };
Function Class
/** * @class * @classdesc cc.NamespaceB.SomeManager */ cc.NamespaceB.SomeManager = function() { /** * init method * @function * @param {string} tag - some tag * @see cc.NamespaceB.SomeManager#funcB */ this.init = function(tag) { }; /** * funcA method * @function */ this.funcA = function() {}; /** * funcB method * @function */ this.funcB = function() {}; };
Function Class Singleton
cc.NamespaceB.SomeManager = function() { // ...... }; var _sharedSomeManager = null; /** * cc.NamespaceB.SomeManager singleton. * @return {cc.NamespaceB.SomeManager} * @example * // example * cc.NamespaceB.SomeManager.getInstance().funcA(); */ cc.NamespaceB.SomeManager.getInstance = function() { if (_sharedSomeManager == null) { _sharedSomeManager = new cc.NamespaceB.SomeManager(); _sharedSomeManager.init(); } return _sharedSomeManager; };
Callback Function
cc.NamespaceB.SomeManager = function() { // ...... /** * callBackFunc method * @function * @param {cc.NamespaceB.SomeManager~customCallback} callbackFunc - A callback function. */ this.funcWithCallback = function(callbackFunc) { callbackFunc(); } /** * This callback for funcWithCallback method. * @callback cc.NamespaceB.SomeManager~customCallback * @param {object} event - Event object. */ };
jsdoc Online Document
Generate
To generate a online doc is pretty simple. First we need to a conf.json
:
{ "tags": { }, "source": { "include": [ "../SampleProject/src/MainMenuScene.js" ] }, "plugins": ["plugins/markdown"], "templates": { "cleverLinks": false, "monospaceLinks": false } }
Then we can generate the doc using the following command:
root$ jsdoc -c ./conf.json -d ./docs
The generated doc is under ./docs
and we can access it by opening index.html
:
jsdoc Template
The default generated doc dose look that good but we can use some beautiful template && customize to make it looks good.
Download any template you like, unzip it and then use it like this:
shell
root$ jsdoc -c ./conf.json -d ./docs -t ./template/docdash-master
Now here comes our pretty pretty look doc:
Customize Template
To customize the template is also a piece of cake. For example the color of the link text here is not good :
We can use the Chrome Developer Tools -- Elements -- Inspect
to quick locate the elemnet we want and check the style:
and we can change the property on the fly:
and finally we just need to apply the changes to the corresponding css
file:
.type-signature > a { color: #D6FDC4; }
and regenerate the doc and that’s all:
jsdoc markdown
jsdoc-to-markdown can generate formatted markdown
doc which is another cool way to share the doc:
jsdoc2md ./SampleProject/src/MainMenuScene.js > api.md