jsdoc3 学习笔记

文章参考

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

扫描二维码关注公众号，回复： 305764 查看本文章

常用指令

/**
 * 机构纵向树形表
 * @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;
        },

猜你喜欢