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("大家好!","请大家多多关照,谢谢。");

生成文档,截图展示:
jsdoc.JPG

posted on 2008-11-25 10:59 -274°C 阅读(10954) 评论(5)  编辑  收藏 所属分类: web前端


FeedBack:
# re: JsDoc 介绍
2008-11-25 11:39 | ddd
搞得不丑,顶一个  回复  更多评论
  
# re: JsDoc 介绍[未登录]
2008-11-25 18:27 | -274°C
@ddd

谢谢支持。  回复  更多评论
  
# re: JsDoc 介绍
2008-11-25 23:07 | EricFan
很好的东西,试用一下,不过就我们那个代码写得,有这工具也没啥用  回复  更多评论
  
# re: JsDoc 介绍[未登录]
2008-11-26 00:11 | -274°C
@EricFan 按这种注释规范写,就可以了。  回复  更多评论
  
# re: JsDoc 介绍
2008-11-26 19:08 | BeanSoft
以前有个Perl写的JsDoc项目, 用着麻烦, 这个Java版本的好!  回复  更多评论
  

只有注册用户登录后才能发表评论。


网站导航:
 

常用链接

留言簿(21)

随笔分类(265)

随笔档案(242)

相册

JAVA网站

关注的Blog

搜索

  •  

积分与排名

  • 积分 - 871703
  • 排名 - 37

最新评论