使用SmartDoc自动化构建NodeJS服务器文档

写在前面

还在为编码后苦苦写文档皱眉么, NodeJS 服务器开发同学的福利来了~

使用 SmartDoc 工具, 在开发的时候随手将代码格式化一下, 你的文档就 duang~~的一下灰来了~~

环境

NodeJS + NPM

安装支持

到你的项目的 package.json 目录下执行以下命令, 安装必要模块

npm install grunt grunt-contrib-smartdoc –save-dev

然后就可以看到 devDependencies 下面多了两个

"grunt": "^0.4.5",
"grunt-contrib-smartdoc": "^0.1.1",

说明成功 lol

PS: 如果不使用 grunt 方法, 也可以自行安装 smartdoc 也阔以, 但是个人认为比较麻烦啦, 还是 grunt 好

npm install smartdoc -g

配置文件 - 基于 Grunt 很方便啦

Gruntfile.js

module.exports = function (grunt) {
    grunt.initConfig({
        pkg: grunt.file.readJSON('game-server/package.json'),
        smartdoc: {build: {options: {
        paths: ["game-server/"],    // 这里要改成需要解析文档的目录
        outdir: 'docs/',        // 这个是文档输出的文件夹
        project: {
        name: '<%= pkg.name %>',    // 这是解析package.json获取相关信息的代码
        description: '<%= pkg.description %>',
        version: '<%= pkg.version %>',
        url: '',    // 这个是文档的Home目录
        // 这个数组是生成了注释后网页头部banner导航栏, 可以不写啦
        navs: [
            {name: "Home", url: ""},
            {name: "Author", url: "https://game.cocosplayer.com/"}
        ]
        }}}
        }
    });

    grunt.loadNpmTasks('grunt-contrib-smartdoc');
    grunt.registerTask('default', ["smartdoc"]);
};

以后在跟目录执行 grunt 命令即可重新生成文档咯 ~~lol~~

代码注释的写法

可以参考我的另一篇文字: <使用 SmartDoc-YUIDoc 自动生成 Node 文档>

如何编写文件头注释

/**
 * @filename Demo - 这里写文件名, 不要扩展名就阔以啦~\(≧▽≦)/~
 *
 * <p> 这里还可以写一些文件的说明啥的 </p>
 *
 * @module ServerModule - 这个是重头戏, 文件属于哪个模块, 尽量在这里定义好
 *
 * @author OnO<corn.mars@ono.lol>
 * @version 1
 * @time 2015/8/26 16:48
 */

小窍门

如果使用 WebStorm 的同学, 可以定义创建文件的文件模板如下, 就可以大概生成如上的格式

/**
 * @filename ${NAME}
 *
 * @module ${PACKAGE_NAME}
 *
 * @author OnO<corn.mars@ono.lol>
 * @version 1
 * @time ${DATE} ${TIME}
 */

如何编写对象注释 - 包括类属性

/**
 * Demo Handler 对象的说明
 *
 * @class DemoHandler 这个就写对象名就写了
 * @param {Object} app 这里一一列举对象属性
 * @constructor 这个标记表示该方法是对象(因为JS是用函数模拟的对象,所以你懂的~)
 */
function DemoHandler(app) {
    /**
     * App Instance 这里写对象的属性的注释
     *
     * @property app 就写属性名就写了
     * @type {Object} 标记属性的类型
     */
    this.app = app;
}

如何编写类方法注释

/**
 * Demo handler 这里写类方法(普通方法和原型方法)的注释
 *
 * @method shot 就写方法名
 * @for DemoHandler 强制标记为该方法是哪个类的, 其实在一个文件中, 写了"DemoHandler.prototype." 或者 "DemoHandler."的话也是可以识别的
 *
 * @param {Object} msg message from client    这就是我们常写的参数列表啦, 注意类型
 * @param {Object} session
 * @param {Function} next next stemp callback
 *
 * @async 这是标记该方法是否是异步方法的
 * @return {Null} 异步方法一般return null; 或者设计成chain的模式return this;
 */
DemoHandler.prototype.shot = function (msg, session, next) {
    var ret = {code: 500};
    next(null, ret);
    session.on("closed", onShot.bind(null, self.app));
    // 此处不写return, 或者写return this;
};

如何编写普通方法注释

/**
 * When Shot Called 普通非类方法
 *
 * @event onShot 方法名
 *
 * @param {Object} app current application
 * @param {Object} session current session object
 */
var onShot = function (app, session) {
    if (!session || !session.uid) {
    return;
    }
    app.rpc.chat.chatRemote.kick(session, session.uid, app.get("serverId"), session.get("rid"), null);
};