简单说，用JSDoc写开发文档就是写注释，只是在书写的时候要把它们按照规范工整的写出来，这样即可达到注释的目的又能顺便地让JSDoc生成规范的文档，两全其美。这样想事情就简单多了不是吗？
怎么做?
我这里只讲在node.js平台下的操作步骤。
全局安装JSDoc依赖包：
npm i jsdoc -g
随便写一个带有JSDoc注释的js文件吧：
/**
* JSDoc Demo File
* see more link to <a href="http://blog.pagegaga.com">blog.pagegaga.com</a>
* @author Warren <aliang_ok@sina.com>
* @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 <email>
* @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这个利器呢？
网友评论