JSDoc 介绍使用规范JsDoc的使用介绍


Posted in Javascript onFebruary 12, 2011

JsDoc Toolkit不久前发布了2.3.2版本,主要还是对前版本的修复。
如果你需要使用Ant,JsDoc还有一个Ant插件:JsDoc Toolkit Ant Task
下载JsDoc Toolkit2.3.2:http://jsdoc-toolkit.googlecode.com/files/jsdoc_toolkit-2.3.2.zip
命令名描述
@param @argument 指定参数名和说明来描述一个函数参数

@returns 描述函数的返回值
@author 指示代码的作者
@deprecated 指示一个函数已经废弃,而且在将来的代码版本中将彻底删除。要避免使用这段代码
@see 创建一个HTML链接,指向指定类的描述
@version 指定发布版本
@requires 创建一个HTML链接,指向这个类所需的指定类
@throws @exception 描述函数可能抛出的异常的类型
{@link} 创建一个HTML链接,指向指定的类。这与@see很类似,但{@link}能嵌在注释文本中
@fileoverview 这是一个特殊的标记。如果在文件的第一个文档块中使用这个标记,则指定该文档块的余下部分将用来提供这个文件的概述
@class 提供类的有关信息,用在构造函数的文档中
@constructor 明确一个函数是某个类的构造函数
@type 指定函数的返回类型
@extends 指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息,不过,在某些情况下则必须使用这个标记
@private 指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中,除非运行JSDoc时提供了--private命令行选项
@final 指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量
@ignore JSDoc忽略有这个标记的函数

JsDoc:是js文档生成工具,它从javascript程序源代码中抽取类、方法、成员等注释信息形成一个和源代码配套的API帮助文档。
Java开源项目http://www.jsdoctoolkit.org/,它是一个功能强大的javascript文档生成工具。
下面我们来结束一下如何使用。
我们通过下载工具类库。
这里我们使用的是jsdoc_toolkit-2.1.0.zip也是当前的最高版本。
我们将这个文件解压。可以看到里面README.txt文件。
这里有详细的使用说明。【好像介绍到这里就可以了。当然你也可以继续读下】
这里我们需要通过命令行进行创建javascript文档。
java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js
当然如果感觉通过命令行的方式比较麻烦,我们可以自行创建一个.bat文件
将上面的内容复制到该文件中,执行即可。
下面我来简单解释一下这其中的参数
-a 表示全部的方法
-e 表示对应的文件的编码根式 这里对应的是GB18030 默认的是utf-8
-t 表示生产doc的文档样式模板
这里的test/*.js表示在test目录下的全部javascript文件
执行完毕后将文档结果默认输出到/out/jsdoc目录下。当然这个目录也是可以定义的
具体参数可以使用
java -jar jsrun.jar app/run.js --help
进行查看。
结果如下:

OPTIONS: 
-a or --allfunctions 
Include all functions, even undocumented ones. 
-c or --conf 
Load a configuration file. 
-d=<PATH> or --directory=<PATH> 
Output to this directory (defaults to "out"). 
-D="myVar:My value" or --define="myVar:My value" 
Multiple. Define a variable, available in JsDoc as JSDOC.opt.D.myVar. 
-e=<ENCODING> or --encoding=<ENCODING> 
Use this encoding to read and write files. 
-E="REGEX" or --exclude="REGEX" 
Multiple. Exclude files based on the supplied regex. 
-h or --help 
Show this message and exit. 
-n or --nocode 
Ignore all code, only document comments with @name tags. 
-o=<PATH> or --out=<PATH> 
Print log messages to a file (defaults to stdout). 
-p or --private 
Include symbols tagged as private, underscored and inner symbols. 
-q or --quiet 
Do not output any messages, not even warnings.

下面我们来创建test下的js文件
简单的方法标注
myjs.js
/** 
* @fileOverview 简单的方法标注示例 
* @author <a href="llying.javaeye.com">llying</a> 
* @version 0.1 
*/ /** 
* @description 加法运算 
* @param {Num} num1 加数 
* @param {Num} num2 被加数 
* @return {Num} result 结果 
*/ 
function add(num1,num2){ 
return num1 + num2; 
} 
/** 
* @description 减法运算 
* @param {Num} num1 减数 
* @param {Num} num2 被减数 
* @return {Num} result 结果 
*/ 
function minus(num1,num2){ 
return num1 - num2; 
}

类的方法标注
myjs2.js
/** 
* @fileOverview 简单的类对象标注示例 
* @author <a href="llying.javaeye.com">llying</a> 
* @version 0.1 
*/ 
/** 
* @author llying 
* @constructor Person 
* @description 一个Person类 
* @see The <a href="#">llying</a >. 
* @example new Parent(“张三”,15); 
* @since version 0.1 
* @param {String} username 姓名 
* @param {Num} age 年龄 
*/ 
function Person(username,age) 
{ 
/** 
* @description {Sting} 姓名 
* @field 
*/ 
this.username = username; 
/** 
* @description {Num} 年龄 
* @field 
*/ 
this.age = age 
/** 
* @description 弹出say内容 
* @param {String} content 内容 
*/ 
this.say = function(content) 
{ 
alert(this.username+" say :"+content); 
} 
/** 
* @description 返回json格式的对象 
* @return {String} json格式 
* @see Person#say 
*/ 
this.getJson = function(){ 
return "{name:"+this.username+",age"+this.age+"}"; 
} 
}

现在我们可以运行java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js

至此我们的js文档生成完毕。我们也无需羡慕JavaDoc了。
JSDoc 介绍使用规范JsDoc的使用介绍
我们只是列出了常用的标签,至于更多的可以登陆到官方网站查看
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference

Javascript 相关文章推荐
js克隆对象、数组的常用方法介绍
Sep 26 Javascript
用Js实现的动态增加表格示例自己写的
Oct 21 Javascript
js通过location.search来获取页面传来的参数
Sep 11 Javascript
node.js中的fs.closeSync方法使用说明
Dec 17 Javascript
鼠标经过子元素触发mouseout,mouseover事件的解决方案
Jul 26 Javascript
浏览器检测JS代码(兼容目前各大主流浏览器)
Feb 21 Javascript
微信小程序视图template模板引用的实例详解
Sep 20 Javascript
vue组件watch属性实例讲解
Nov 07 Javascript
在vscode中统一vue编码风格的方法
Feb 22 Javascript
小程序组件之自定义顶部导航实例
Jun 12 Javascript
Vue.js组件实现选项卡以及切换特效
Jul 24 Javascript
Vue用mixin合并重复代码的实现
Nov 27 Vue.js
编写可维护面向对象的JavaScript代码[翻译]
Feb 12 #Javascript
URL地址中的#符号使用说明
Feb 12 #Javascript
基于Jquery制作的幻灯片图集效果打包下载
Feb 12 #Javascript
基于jquery的jqDnR拖拽溢出的修改
Feb 12 #Javascript
jQuery1.4.2与老版本json格式兼容的解决方法
Feb 12 #Javascript
在vs2010中调试javascript代码方法
Feb 11 #Javascript
juqery 学习之六 CSS--css、位置、宽高
Feb 11 #Javascript
You might like
PHP Cookie的使用教程详解
2013/06/03 PHP
ThinkPHP使用心得分享-ThinkPHP + Ajax 实现2级联动下拉菜单
2014/05/15 PHP
对PHP PDO的一些认识小结
2015/01/23 PHP
PHP7正式版测试,性能惊艳!
2015/12/08 PHP
两种php实现图片上传的方法
2016/01/22 PHP
thinkphp框架下404页面设置 仅三步
2016/05/14 PHP
PHP哈希表实现算法原理解析
2020/12/11 PHP
jquery 全局AJAX事件使用代码
2010/11/05 Javascript
js 分页全选或反选标识实现代码
2011/08/09 Javascript
JS中attr和prop属性的区别以及优先选择示例介绍
2014/06/30 Javascript
Javascript毫秒数用法实例
2015/02/05 Javascript
jquery实现表单输入时提示文字滑动向上效果
2015/08/10 Javascript
Bootstrap每天必学之工具提示(Tooltip)插件
2016/04/26 Javascript
JavaScript每天必学之数组和对象部分
2016/09/17 Javascript
JS声明式函数与赋值式函数实例分析
2016/12/13 Javascript
jquery插件treegrid树状表格的使用方法详解(.Net平台)
2017/01/03 Javascript
JavaScript事件处理程序详解
2017/09/19 Javascript
使用webpack打包koa2 框架app
2018/02/02 Javascript
vue axios post发送复杂对象问题
2019/06/04 Javascript
使用JS location实现搜索框历史记录功能
2019/12/23 Javascript
基于VSCode调试网页JavaScript代码过程详解
2020/07/20 Javascript
python定时执行指定函数的方法
2015/05/27 Python
Djang中静态文件配置方法
2015/07/30 Python
简述Python2与Python3的不同点
2018/01/21 Python
python3中zip()函数使用详解
2018/06/29 Python
在PyCharm中实现关闭一个死循环程序的方法
2018/11/29 Python
Django media static外部访问Django中的图片设置教程
2020/04/07 Python
python自动化测试三部曲之unittest框架的实现
2020/10/07 Python
详解canvas.toDataURL()报错的解决方案全都在这了
2020/03/31 HTML / CSS
Furla官网:意大利著名的皮革品牌
2019/08/06 全球购物
美国折扣地毯销售网站:Rugs.com
2020/03/27 全球购物
质量月活动策划方案
2014/03/10 职场文书
学校爱心捐款倡议书
2014/05/13 职场文书
2014年局领导班子自身建设情况汇报
2014/11/21 职场文书
如何用JS实现简单的数据监听
2021/05/06 Javascript
80行代码写一个Webpack插件并发布到npm
2021/05/24 Javascript