JSDOC入门
发布在JSDOC入门2014年10月31日view:9509
在文章任何区域双击击即可给文章添加【评注】!浮到评注点上可以查看详情。

什么是JSDOC?

JSDOC是一套javascript文档规范,开发者只要按照规范编写注释,并用JSDOC的文档导出工具即可导出一份非常漂亮(可定制)的html文档. 和其他语言的DOC相比JSDOC的tag会比较多是因为其考虑到js语言层面的一些不足和其灵活的编写方式,JSDOC可能无法理解你的继承关系、你定义一个函数是方法还是构造器等等...这时你就必须通过内置tag来告诉JSDOC如何生成合适的文档,比如:你定义的函数是一个方法还是一个构造器;一个实例方法是public还是protected亦或是private;一个类是否是抽象类等等...你必须自己编写tag来告诉JSDOC:hi,JSDOC,输出的文档请把function Person(){}当成Person类,而不要当成Person函数;请标明Person是一个抽象类等等...然后JSDOC文档生成器就会根据对用户编写注释的tag和它自己对JS语法的解析来输出合适的文档.

JSDOC导出工具的安装.

对于jser而言最直接的安装方法就是用npm 输入:npm install jsdoc -g,-g将其安装到全局命令中.

Hello JSDOC.

首先我们创建一个EditorQ.js文件.接下来我们来定义一个EditorQ类,并为其添加JSDOC注释

/**
* <h4>Hello JSDOC</h4>
* <p>EditorQ是一个演示级别的的富文本编辑器</p>
* @class EditorQ
* @param {object|string} options 配置参数
* @see <a href="www.github.com/songzheng741">源码</a>
* @author songzheng
*/
function EditorQ(options) {
    this.init(options);
    /**
     * @constructs Selection
     * @memberof EditorQ~
     */
    var Selection = function(){};
    /**
     * @constructs Range
     * @memberof EditorQ~
     */
    var Range = function(){};
};
EditorQ.prototype = {
    constructor: EditorQ,
    init: function(){},
    /**
     * @param command 要执行的命令
     */
    execCommand: function(command){}
}

/**
* @memberof EditorQ
*/
EditorQ.version = '0.0.1'

打开你的命令行工具,输入jsdoc EditorQ.js,你会发现在EditorQ.js的同级目录下有一个名为out的文件夹,这就是jsdoc默认放置文档的地方. 用游览器打开index.html页面,一个组织良好的帮助文档已经生成了. enter image description here

在看具体的JSDOC注释之前,让我们先简单了解一下这个程序. EditorQ是一个用来演示用的富文本编辑器.它还没有任何实现.基于IE6,7,8和W3C游览器对于selection和range差异的考虑,EditorQ有两个内部类用来屏蔽掉selection和range的差异,为EditorQ提供统一的接口. 现在让我们回到先前打开的文档页面,我们发现右侧导航已经有了三个class的链接,点击EditorQ,你会看到这样的界面 enter image description here

你会看到JSDOC已经正确的理解了EditorQ类的结构并组织出一份和Java doc非常类似的文档:EditorQ有两个内部类(Range和Selection)一个静态的成员变量(version)和一个实例方法(execCommand) 当然这一切是基于你编写的正确的JSDOC注释和JSDOC对于js语法的解析!! 让我们解析一下这个注释

1 /**
2 * <h4>Hello JSDOC</h4>
3 * <p>EditorQ是一个演示级别的的富文本编辑器</p>
4 * @class EditorQ
5 * @param {object|string} options 配置参数
6*/
function EditorQ(options) {

首先和Java DOC类似JSDOC只会解析/** /的注释.并且/* */是对紧跟它后面代码的解释.

(1)2,3行是对EditorQ类的描述,它可以是一段html

(2)第4行告诉JSDOC EditorQ是一个类而不是一个函数

(3)第五行是对参数的一些解释 这些tag都非常简单并且和其他语言DOC大同小异,

让我们接着往下看,它将引出JSDOC最重要的一个概念namespaths

namepaths

function EditorQ(options) {
    this.init(options);
    /**
     * @constructs Selection
     * @memberof EditorQ~
     */
    var Selection = function(){};
    /**
     * @constructs Range
     * @memberof EditorQ~
     */
    var Range = function(){};
};

namepaths其实也很简单,它指的是一个变量的引用路径和方式 namepaths @memberof EditorQ~ 告诉JSDOC:Selection是EditorQ的一个内部变量,并且在输出的文档为Selection页面增加EditorQ的导航.因为其实内部变量所以它是没有引用路径的. 我们再来看一个更好说明namepaths的例子,它是JSDOC官网的事例 ,我对它稍加修改.

/** @class */
var Person = function() {
    /**
     * @method say
     * @memberof Person#
     * @returns {string}
     */
    this.say = function() {
        return "I'm an instance.";
    }

    /**
     * @memberof Person~
     * @returns {string}
     */
    function say() {
        return "I'm inner.";
    }
}

/**
 * @method say
 * @memberof Person.
 * @returns {string}
 */
Person.say = function() {
    return "I'm static.";
}

var p = new Person();
p.say();      // I'm an instance.
Person.say(); // I'm static

@lends

在JSDOC无法理解方法和变量属于(比如使用mix方法)用lends指明方法和变量是属于那个对象或类,其实他和@memberof的功能基本相同

/** @class */
var Person = makeClass(
    /** @lends Person */
    {
        /**
         *
         * @param name
         */
        initialize: function(name) {
            this.name = name;
        },
        /**
         *
         * @param message
         * @returns {string}
         */
        say: function(message) {
            return this.name + " says: " + message;
        }
    }
);

JSDOC注意事项

(1)@description可以正确理解折行,但@description后面不可以不写内容紧跟下一个tag

(2)private 变量默认是不输出到文档中的.

(3)为什么定义一个实例方法或静态方法而文档中没有输出?

很可惜,现阶段的JSDOC好像识别不出实例方法和静态方法,请添加tag,@method明确指定其是一个方法,并配合namepaths指定它是什么类型的方法

Tag列表 JSDOC官网

.

评论
发表评论
4年前

表示用过。。。

WRITTEN BY
前端_三丝
虽是js菜鸟,但梦想成为小牛的那天
TA的新浪微博
PUBLISHED IN
JSDOC入门

JSDOC入门教程

我的收藏