Jsdoc的安装及使用方法

　　jsdoc用于生成脚本文档的自动化工具

一、安装

所有安装方式基于node环境使用npm安装，未安装node环境的小伙伴可参考：https://www.cnblogs.com/bluedream2009/archive/2012/03/17/2402843.html

jsdoc安装命令：

npm i jsdoc -g （全局安装）

jsdoc ink-docstrap模板安装命令：

在当前项目脚本目录下执行此命令

npm install ink-docstrap（局部安装）

jsdoc tui-jsdoc-template模板安装命令：

在当前项目脚本目录下执行此命令

npm i -D tui-jsdoc-template（局部安装）

以上两种模板任选其一，以下模板未验证过：

二、配置

放置在项目脚本根目录下

jsdoc ink-docstrap配置文件：

jsdoc tui-jsdoc-template配置文件：

配置部分示例：

"source": {

"include": ["business","control","dialog","item","layer","lib","scene","sdk"], 需要遍历的目录

"exclude": ["business/gameProtocol.js","scene/out"], 不需要遍历的目录

"includePattern": ".+\\.(js|es)$"

}

基于现有项目的目录配置

"opts": {

"template": "node_modules/tui-jsdoc-template", 文档所使用的模板

"destination": "./docs_tui/" 文档输出目录

}

配置修改，可参考

三、 使用jsdoc生成文档

进入到项目脚本根目录下，执行命令：

Jsdoc –c 配置名称.json

输入命令后，将按照配置文件中的配置项，相应生成，以上提供的两个配置文件，均已配置默认输出目录，可自由更改

四、 Jsdoc注释规范

注释规范参考：

https://www.css88.com/doc/jsdoc/index.html

以下内容仅作为参考

工具	优点	缺点
JSDoc3	提供了完整的模板开发、事件触发等接口，使用非常灵活。	对代码要求比较严格，学习曲线较高。
YUIDoc	不止支持JS语言，更加抽象，如果同时使用了 Ruby/PHP/Python等语言YUI都可以使用。	功能更加抽象，具体实现方面考虑不全。
Dox	轻量级、高度可定制化，兼容JSDoc3语法。	后期会有较多问题需要自己解决。
Docco	行间注释方式，更注重实现过程的文档	不太适合API注释
JSDuck	代码实时修改、语法灵活、支持MarkDown语法，支持查看源码并且文档可读性较高，最主要的是上手非常快。	可定制化支持不足，略显臃肿。

总结：

建议代码中混合了es6的项目，jsdoc比较适合，在未使用es6的情况下，比较推荐jsduck

jsdoc的学习成本较高，小伙伴们可以根据自己实际情况选择