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/" 文档输出目录
}
配置修改,可参考
https://github.com/nhnent/tui.jsdoc-template
https://github.com/docstrap/docstrap
三、 使用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的学习成本较高,小伙伴们可以根据自己实际情况选择