JSDoc在Node.js下的部署

简单说，用JSDoc写开发文档就是写注释，只是在书写的时候要把它们按照规范工整的写出来，这样即可达到注释的目的又能顺便地让JSDoc生成规范的文档，两全其美。这样想事情就简单多了不是吗？

怎么做?

我这里只讲在node.js平台下的操作步骤。

全局安装JSDoc依赖包：

npm i jsdoc -g

随便写一个带有JSDoc注释的js文件吧：

    /** 
     * JSDoc Demo File
     * see more link to blog.pagegaga.com
     * @author Warren 
     * @copyright Warren 2016
     */

    /** 
     * Say hello.
     * @param {string} str - Anything what you want to say.
     */
    var app=function(str){
        alert('hello');
    }

然后就能在项目根目录下执行命令，对要生成文档的文件做解析了：

jsdoc ./

上面这段命令是说对项目根目录（不包括子目录）下所有文件做解析，这样做的结果是JSDoc解析指定目录所有包含以JSDoc规范书写注释的文件，并在默认目录（./out）下生成可供浏览器访问的html文件及相关依赖（包括样式、字体、脚本等）文件。执行完成后，就可以在项目根目录里找到./out/index.html文件双击预览了。

JSDoc 提供了很多命令行参数，可以看官方文档关于命令行相关的说明，这里简单举个例子：

我们可以执行npm i docdash --save-dev安装一个第三方的主题包，然后执行如下命令：

jsdoc ./app.js -d ./doc -t ./node_modules/docdash

结果是，JSDoc把app.js中的注释生成文档并放到了指定目录（./doc）下，同时生成的文档套用了docdash主题。

在命令行里执行命令每次都要重写一遍那些冗长的配置参数很麻烦，不怕，JSDoc可以引用外部配置文件让事情一劳永逸：

在项目目录下新建一个名为jsdoc.cfg.json的配置文件，然后以JSON格式填写如下内容到这个配置文件中:

    {
        "source":{
            "include":[".","./server/"],
            "exclude":["./node_modules/"]

        },
        "opts":{
            "template":"node_modules/docdash",
            "encoding":"utf8",
            "destination":"./jsdoc/",
            "readme":"readme.md"
        }
    }

关于这些配置项的解释，可以在官网找到。保存后，再执行如下命令：

jsdoc -c jsdoc.cfg.json

这样，JSDoc就会按照指定的配置文件中的配置信息来处理文档了。

了解清楚如何生成文档，剩下的问题就是怎么写规范的注释才能生成像样的开发文档了。

怎么写？

JSDoc注释以/**开头*/结尾，并且每一行开头都有一个*。在注释段内通过以@开头的标签为代码提供注解，JSDoc根据这些标签来组织文档结构，套用样式最终生成文档。我们在这里只举几个常用的例子：

每个模块都可以有这样的标签：

    /** 
     * description
     * description more
     * @author author name 
     * @copyright copyright information
     */

description 用来描述代码段，其中可以插入html元素，比如一个a链接，
@author可以注明该代码块的作者，
@copyright用来声明版权。

function：

    /** function description
     * @param {type} paramName - description
     * @returns {type} description
     */

@param 用来描述函数参数，{type}是一个内联标签，用来注明该参数的类型（比如string、object、number），-后面再写该参数的描述文字；
@returns用来标注该函数最终返回什么类型的值并加以说明。

模块：

    /** module description
     * @module
     */

@module 后面可以跟模块名，如果不写，JSDoc会自动取名。

JSDoc提供了丰富的标签，官网文档为我们做了详细讲解，务必去阅读下。

代码用法列举：

可以用@example为添加代码应用案例，以实际用例说明代码的用法：

    /** description
     * @example
     * app('hello');//调用方法
     */

上面看起来很简单对吗？然而它可以做更多！通过JSDoc插件机制可以支持解析并嵌入markdown、通过解析node.js的package.json构建文档的目录结构等诸多功能让文档变得更饱满。

想要让项目工程化进展得更顺溜，怎能少了JSDoc这个利器呢？