文章参考
http://www.css88.com/doc/jsdoc/index.html
介绍
SDoc 3是一个生成Javascript API文档的工具。
下载地址为:https://github.com/jsdoc3/jsdoc 。
安装
1、使用JSDoc 3 我们需要有Node.js环境。
2、使用npm安装jsdoc
常用指令
/** * 机构纵向树形表 * @module orgMindChart */
备注:定义了一个 module,这个module的名字叫 orgMindChart
@module可以将当前文件标注为一个模块,默认情况下文件内的所有标识符都隶属于此模块,除非文档另有说明。
个人理解: 一个文件就是一个模块,必须按照模块化变成的思路编写代码。
@class
描述:此函数旨在需要使用"new"关键字调用,即构造函数。
别名:@constructor
备注:@class 和 @constructor是一模一样的,没有区别
如果未提供模块的名称,那么JSDoc将从模块的路径和文件名获得模块名称?
1、Person#say // 名为"say"的实例方法
2、Person.say // 名为"say"的静态方法
3、Person~say // 名为"say"的内部函数
class('trackr.CookieManager',
/**
* @class
* @alias huangbiao
* @param {Object} kv
*/
function(kv) {
/** The value. */
this.value = kv;
}
);
在@alias标签告诉JSDoc处理匿名函数,就好像它是 “trackr.CookieManager”类的构造函数。
在这个函数中,JSDoc将this关键字解释为huangbiao,因此,“value”方法的namepath(名称路径)为“huangbiao#value”。
@memberof标签标明成员隶属于哪一个父级标识符。
/** @namespace */ var Tools = {}; /** @memberof Tools */ var hammer = function() { }; Tools.hammer = hammer;
“@memberof!”,
来描述对象(Data#point)的属性,它是一个类(Data)的实例成员。
/** @function */
var paginate = paginateFactory(pages);
如果没有@function标记,paginate对象将被记录为一个一般的对象(一个@member),因为在这行代码运行时,它不可能分辨检查paginate是什么类型的值。
var paginate = paginateFactory(pages);
案例一:基本类的使用
/** * 定义的一个Person类,用来创建人这个对象 * @constructor Person */ function Person(){ this.name = "huangbiao"; } /** * Person 这个类原型链上的数据 * @type {{age: number, sex: string}} * @namespace pserson.prototype */ Person.prototype = { /** * 年龄 */ age : 28, /** * 获取年龄 * @returns {number} */ getAge:function(){ return this.age; }, /** * 性别 */ sex : "男", /** * 获取性别 * @returns {number} */ getSex:function(){ return this.age; } };
备注:这里只是单纯的定义了一个类,没有“闭包”等其他复杂的逻辑破坏结构,因此不需要使用@alias指令
案例二:类的对象方法、内部方法等
/** * 定义一个Person类 * @constructor * @alias PersonClass */ Person = function() { /** * 该方法为Person对象的方法 * @returns {string} */ this.say = function() { return "I'm an instance."; }; /** * 该方法为Person对象内部的方法 * @returns {string} */ function say() { return "I'm inner."; } };
备注:这里体现了@alias 指令替换对象的方法
案例三:命名空间
/** * A namespace. * @namespace MyNamespace */
备注:MyNamespace 是用户自定义命名空间的名字
/** * personObj 这个类原型链上的数据 * @type {{age: number, sex: string}} * @namespace personObj */ personObj = { /** * 年龄 */ age : 28, /** * 性别 */ sex : "男" };
案例四:闭包(重点)
(function(){ /** * 定义的一个Person类,用来创建人这个对象,是一个构造函数 * @constructor * @alias Person */ function Person(){ this.name = "huangbiao"; } /** * Person 这个类原型链上的数据 * @type {{age: number, sex: string}} */ Person.prototype = { /** * 年龄 */ age : 28, /** * 获取年龄 * @returns {number} */ getAge:function(){ return this.age; }, /** * 性别 */ sex : "男", /** * 获取性别 * @returns {number} */ getSex:function(){ return this.age; } }; //return Person; })();
/**
* 定义的一个Person类,用来创建人这个对象,是一个构造函数
* @constructor
* @alias Person
*/
@constructor 后面不要命名
@alias 一定要有名称,表示这个构造函数后面的this全部用这个别名代替
案例五:综合案例
案例六:扩展module模块
@example 添加示例代码
/** * 判断是否 Function 对象 * @param obj 被检测数据 * @returns {boolean} * @example * * function abc(){} * var simpleDemo = inherit(BaseClassExtend.prototype); * alert(simpleDemo.isFunction(abc)); */ isFunction : function(obj){ if('[object Function]' == this.checkDataType(obj)){ return true; } return false; },