实践｜开始使用JsDoc

JsDoc可以根据规范化的注释、自动生成接口文档。包括参数说明、示例等等。

一、安装

sudo npm install jsdoc -g

二、制作第一份文档

jsdoc demo.js

只有一个参数、代表js源代码。可以是文件名、也可以是一个路径

jsdoc ./ 

demo.js代码如下：

/**
ok类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
    this.title=title;
    this.author=author;
}
Book.prototype={
    /**
     * 获取书本的标题
     * @returns {string|*}
     */
    getTitle:function(){
        return this.title;
    },
    /**
     * 设置书本的页数
     * @param pageNum {number} 页数
     */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};

文档默认会输出到./out目录中：

生成的文件夹

在浏览器中打开index.html即可看到。

生成的文档

三、遇到了闭包的问题

闭包中定义的Class是不能被识别的。比如下面这段代码：

(function(rcu){
    /**
     * Creates a new Person.
     * @class
     */
    function Person(){
    };
    
    Person.prototype = {
        /**
         * 获取书本的标题
         * @returns {string|*}
         */
        getTitle:function(){
            return this.title;
        },
        /**
         * 设置书本的页数
         * @param pageNum {number} 页数
         */
        setPageNum:function(pageNum){
            this.pageNum=pageNum;
        }
    }

    rcu.Person = Person;
})(window.util);

其中定义的类文档以及方法文档根本到不出来。大概原因是Person在闭包中、不在全局命名空间中，JsDoc无法识别。

于是我改成了下面这种写法：

(function(rcu){
    /**
     * Creates a new Person.
     * @class
     */
    rcu.Person = function(){

    };

    rcu.Person.prototype = {
        /**
         * 获取书本的标题
         * @returns {string|*}
         */
        getTitle:function(){
            return this.title;
        },
        /**
         * 设置书本的页数
         * @param pageNum {number} 页数
         */
        setPageNum:function(pageNum){
            this.pageNum=pageNum;
        }
    }
})(window.util);

这样、文档注释就能被识别了。虽然写法怪异了点、暂时先用着吧。截图留念～～

四、几个栗子

例子：对类的注释

    /**
     * Creates a new Person.
     * @class
     * @example
     * // returns 2
     * globalNS.method1(5, 10);
     * @author wanghuan
     */
    rcu.Person = function(){

    };

• 第一行代码描述信息
• @class表明这是一个类
• @example下面是示例代码
• @author后面是作者

例子：对接口的注释

    /**
     * 获取书本的标题
     * @param pageNum {number} 页数
     * @returns {string|*}
     */
    getTitle:function(){
        return this.title;
    }

• 不需要声明这是一个方法
• 第一行代表描描述息
• @param 参数说明
• @returns 返回值说明

。。。。。。。。老大说不能再玩了。。。。。我要去写业务了啊～～～～～

五、参考文档

1. 官方文档：http://usejsdoc.org/