zyl910

优化技巧、硬件体系、图像处理、图形学、游戏编程、国际化与文本信息处理。

  博客园 :: 首页 :: 博问 :: 闪存 :: 新随笔 :: 联系 :: 订阅 订阅 :: 管理 ::
  215 随笔 :: 0 文章 :: 145 评论 :: 111万 阅读
< 2025年2月 >
26 27 28 29 30 31 1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 1
2 3 4 5 6 7 8

作者: 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”)。

其次,遇到了环境变量与相对路径问题——

  1. 因“jsduck-5.3.4.exe”是单独下载的exe,没注册环境变量。所以我们在命令提示符中使用时,只有进入到此exe的所在目录中才能使用,否则会报错找不到exe。
  2. “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,便可生成文档。不用在“命令提示符”手工敲命令了。

img_bat.png

有时会遇到 in "mkdir": Permission denied 这样的错误信息,这一般是因文件临时被安全软件锁定了所引起的。再双击bat重新生成就行。

四、生成效果

img_home.png

img_cat.png

范例代码:

/** 动物.
 */
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

参考文献

posted on   zyl910  阅读(993)  评论(0编辑  收藏  举报
编辑推荐:
· .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指令集 处理 双精度浮点数组求和
点击右上角即可分享
微信分享提示