作者: zyl910
一、工具比较
为了让前端JavaScript程序更具可维护性,更利于团队开发,文档非常重要。此时便需要使用自动化文档工具了。
我对比了各种JavaScript自动化文档工具,发现JSDuck最适合我。它的优点有——
- 生成文档的易读性高,界面美观。
- 文档注释的语法简单,功能丰富,能比较随意的编写文档注释。
- 对于 构造函数、闭包、极简主义 这3种方法定义的类,均能正确识别、生成文档。
- 提供了打包好的exe,可直接在Windows下使用,不用安装 ruby 环境。且其文件小,只有3MB左右,很适合放在代码目录中。
JSDuck强力功能点如下:
- 树形类命名空间组织
- 类子父关系的层次体系展示
- 成员与事件和配置项快速索引
- 可穿插着色代码范例演示和编辑范例代码
- 类成员源码实现部分快速导航
二、下载与环境安装
JSDuck推荐的安装办法是——先装好ruby环境,然后用gem或apt-get等命令安装JSDuck。
对于Windows平台,它还提供了打包好的exe。下载下来后直接可以用,无需安装ruby环境。
JSDuck的发布地址是——
https://github.com/senchalabs/jsduck/releases
它目前的稳定版是 5.3.4,可点击上述页面中的“jsduck-5.3.4.exe”进行下载。
三、命令行与使用心得
JSDuck是一个命令行程序,故其基本用法是——通过命令行配置好参数,然后执行该命令生成文档。
为了避免每次敲命令的重复劳动,它还提供了 --config 参数,后面接一个JSON配置文件(一般为config.json)的路径。这便能使用JSON配置中的参数了。
命令行与--config方式并不是互斥的,可同时使用。你可自由的决定哪些参数放到配置文件中,哪些直接写在命令行中。
JSDuck命令行的格式为——
jsduck [options] files/dirs...
可使用 --help 参数来查看帮助。
jsduck --help
3.1 Windows 下的使用心得
首先,因为我们现在是直接使用下载的“jsduck-5.3.4.exe”。因文件名不同,所以不能像官方教程那样用“jsduck”命令,而应该用“jsduck-5.3.4.exe”(或“jsduck-5.3.4”)。
其次,遇到了环境变量与相对路径问题——
- 因“jsduck-5.3.4.exe”是单独下载的exe,没注册环境变量。所以我们在命令提示符中使用时,只有进入到此exe的所在目录中才能使用,否则会报错找不到exe。
- “jsduck-5.3.4.exe”运行时,是先在临时目录中解压后再运行的,导致其当前目录与之前的不同。导致无法使用相对目录,特别是不适合在 config.json 中使用目录。但若写成绝对路径,却又没有通用性。
这些问题可通过Windows批处理来解决。因为批处理提供 %~dp0 变量来代表当前目录,这便可以方便的指定目录了。
例如JavaScript源码在“src”子目录,准备将文档生成到doc目录时,批处理(jsduck_make.bat)可这样写——
%~dp0jsduck-5.3.4.exe --output="%~dp0doc" --images="%~dp0images" --builtin-classes --title="test_jsduck: Test JSDuck" "%~dp0src"
pause
参数说明——
参数 | 说明 |
---|---|
--output="%~dp0doc" | 设置输出目录为当前目录下的“doc”子目录 |
--images="%~dp0images" | 设置输出目录为当前目录下的“images”子目录 |
--builtin-classes | 建javascript语言内建类文档,如Array或Object类的使用说明。 |
--title="test_jsduck: Test JSDuck" | 设置文档标题 |
"%~dp0src" | 没有其他命令约束的,就是源码目录(或文件),能支持多个源码目录。这里是将当前目录下的“src”子目录作为源码目录 |
在资源管理器中双击该bat,便可生成文档。不用在“命令提示符”手工敲命令了。
有时会遇到 in "mkdir": Permission denied
这样的错误信息,这一般是因文件临时被安全软件锁定了所引起的。再双击bat重新生成就行。
四、生成效果
范例代码:
/** 动物.
*/
var Animal = {
/** 创建 动物.
*
* @return {Animal} 返回所创建的对象.
* @static
*/
createNew: function(){
var animal = {};
/** 睡觉.
*/
animal.sleep = function(){ alert("睡懒觉"); };
return animal;
}
};
/** 猫.
*
* @extends Animal
*/
var Cat = {
/** 声音.
* @static @protected
*/
sound : "喵喵喵",
/** 创建 猫.
*
* @return {Cat} 返回所创建的对象.
* @static
*/
createNew: function(){
var cat = Animal.createNew();
/** 发声.
*/
cat.makeSound = function(){ alert(Cat.sound); };
/** 修改声音.
* @param {String} x 声音.
*/
cat.changeSound = function(x){ Cat.sound = x; };
return cat;
}
};
JSDuck对于 构造函数、闭包、极简主义 这3种方法定义的类,均能正确识别、生成文档。完整的范例源码地址:
https://github.com/zyl910/test_jsduck
参考文献
- 官网: https://github.com/senchalabs/jsduck
- 官方wiki: https://github.com/senchalabs/jsduck/wiki
- yeelan0319《Javascript自动化文档工具:YUI Doc, JSDoc 3, JSDuck等比较》. https://segmentfault.com/a/1190000002579067
- mymickey《Jsduck:前端文档生成利器Jsduck介绍及安装使用》. http://lzw.me/a/jsduck-doc.html
- 阮一峰《Javascript定义类(class)的三种方法》. http://www.ruanyifeng.com/blog/2012/07/three_ways_to_define_a_javascript_class.html
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· .NET Core 托管堆内存泄露/CPU异常的常见思路
· PostgreSQL 和 SQL Server 在统计信息维护中的关键差异
· C++代码改造为UTF-8编码问题的总结
· DeepSeek 解答了困扰我五年的技术问题
· 为什么说在企业级应用开发中,后端往往是效率杀手?
· 清华大学推出第四讲使用 DeepSeek + DeepResearch 让科研像聊天一样简单!
· 推荐几款开源且免费的 .NET MAUI 组件库
· 实操Deepseek接入个人知识库
· 易语言 —— 开山篇
· Trae初体验
2016-10-26 [文明6] 最大化利用工厂等影响6格建筑的六边形网格规划(2016-10-27增加五、六节,19城+133锤方案,37城+259锤方案)
2012-10-26 [C] 跨平台使用Intrinsic函数范例3——使用MMX、SSE2指令集 处理 32位整数数组求和
2012-10-26 [C] 跨平台使用Intrinsic函数范例2——使用SSE2、AVX指令集 处理 双精度浮点数组求和