jsDoc

JsDoc

如果你在写javascript，是否羡慕过C++，JAVA的文档自动生成工具？是否希望自己的程序也能自动生成一份对应的文档，犹如java API文档一样呢？不要再羡慕了。jsdoc_toolkit.zip 一款强大的js doc生成工具已经能完成你所羡慕这些功能了。

你可以访问该工具的主页：http://www.jsdoctoolkit.org/ 查看相关用法。这是一个JAVA开发的开源项目，下面只是记录一些使用过程中常见的细节：

将下载的 jsdoc_toolkit.zip解压后，其中的README.txt 有使用说明。 我可不想每次用的时候都去命令下做这些操作，于是我在解压后的目录里新建了一个run.bat 内容编辑如下：

java -jar jsrun.jar app/run.js -a -t=templates/jsdoc js/*.js

根据上面的命令，建立一个目录，名字为 js 。显然我们将需要提取文档的js文件命名为*.js ，并且放在js目录下，执行run.bat就OK。

什么这么简单？ 对就是这么简单，不过，你的js文件符合jsdoc规范吗？

如果你发现自己操作起来不是那么顺利，那么：

http://www.jsdoctoolkit.org/wiki/?page=Tag%20Reference 主页上的这篇文章对你有所帮助，意思就是你的注释应该符合他的标准。

有人说我英语太差，好吧。我就把常见的一些注释规范或者是他jsdoc工具能识别的标识写出来：

@author:作者

@argument:参数

@augments：参数

@class： 类

@constant：常数

@constructor：构造

@constructs： 构造

@default：默认值

@deprecated： 推荐，说明使用一个变量已不再支持

@description：说明

@example ：范例

@extends： 扩展 ，继承

@field：变量（非功能）

@fileOverview ：整个文件信息

@function： 功能 (表示该变量指向一个功能)

@inner || @private : 私有，内部

@ignore： 忽视 （文档生成的式后也将忽视这个变量）

@event：事件

@version：版本

@type：类型 描述预期的类型变量的值或返回值的函数

@throws :可能抛出的异常

@static： 静态，访问该变量不需要实例

@since： 自 （表明某属性特征，是在什么版本之后才有的）

@see： 描述相关的资源

@scope ||@lends： 作用域

@return ||@returns

@requires： 描述必须需要的资源

@public： 说明内在变量是公开的

@property ： 属性

@param：参数

@namespace： 命名空间

较多用法如下：

eg:

/**

 * @fileOverview 功能接口调用

 * @author -274°C

 * @constructor BlogJava.Data

 * @description [数据结构]命名空间

 * @see The <a href="http://www.example.com">Example Project</a>.

 * @param  {NULL_PARAMETER} objNull 

 * @param  {Function} [fnCallback="null"] :如果不是函数类型,则进行同步调用

 * @return {Boolean} json ：作为回调参数返回

 * @example new KxEFileMon.Data.NULL_PARAMETER("a")

 */

 

以一个完整例子来演示下效果吧：Test.js 随手敲的，至于这个脚本细节就请大家别去考究。

/**
 * @fileOverview 楼主信息描述
 * @author -274°C
 */
 
 /**
 * @constructor LZInfo
 * @description 自我介绍
 * @see The <a href=" http://www.blogjava.net/JAVA-HE">-274°C</a>.
 * @example new LZInfo();
 */
function LZInfo()
{
 /**
 * @description {String} 姓名
 * @field
 */
 this.Name = "hechangmin";
 /**
 * @description 打招呼
 * @param {String} title  说话标题
 * @param {String} content 说话内容
 * @return {Num} nResult 返回结果
 */
 this.SayHello = function()
 {
   alert( arguments[0] + " my name is " + this.Name + arguments[1]);
 }
}

//var lz = new LZInfo();
//lz.SayHello("大家好!","请大家多多关照，谢谢。");

生成文档，截图展示：