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 相关文章推荐
简单实用jquery版三级联动select示例
Jul 04 Javascript
JQuery实现的购物车功能(可以减少或者添加商品并自动计算价格)
Jan 13 Javascript
CSS+JS实现点击文字弹出定时自动关闭DIV层菜单的方法
May 12 Javascript
javascript实现获取服务器时间
May 19 Javascript
解决jquery无法找到其他父级子集问题的方法
May 10 Javascript
JS获取当前使用的浏览器名字以及版本号实现方法
Aug 19 Javascript
JS动态遍历json中所有键值对的方法(不知道属性名的情况)
Dec 28 Javascript
AngularJS框架中的双向数据绑定机制详解【减少需要重复的开发代码量】
Jan 19 Javascript
jQuery插件autocomplete使用详解
Feb 04 Javascript
JavaScript之iterable_动力节点Java学院整理
Jun 29 Javascript
微信小程序的生命周期的详解
Oct 19 Javascript
jQuery zTree树插件的使用教程
Aug 16 jQuery
编写可维护面向对象的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编程最快明白》第二讲 数字、浮点、布尔型、字符串和数组
2010/11/01 PHP
php图片上传存储源码并且可以预览
2011/08/26 PHP
幻宇的层模拟窗口效果-提供演示和下载
2007/01/20 Javascript
JavaScript 代码压缩工具小结
2012/02/27 Javascript
javascript小组件 原生table排序表格脚本(兼容ie firefox opera chrome)
2012/07/25 Javascript
jquery插件jquery.beforeafter.js实现左右拖拽分隔条对比图片的方法
2015/08/07 Javascript
JavaScript的Backbone.js框架的一些使用建议整理
2016/02/14 Javascript
Node.js连接postgreSQL并进行数据操作
2016/12/18 Javascript
jquery表单插件form使用方法详解
2017/01/20 Javascript
JQueryEasyUI框架下的combobox的取值和绑定的方法
2017/01/22 Javascript
JS 验证密码 不能为空,必须含有数字、字母、特殊字符,长度在8-12位
2017/06/21 Javascript
js判断传入时间和当前时间大小实例(超简单)
2018/01/11 Javascript
react实现换肤功能的示例代码
2018/08/14 Javascript
详解vuex之store拆分即多模块状态管理(modules)篇
2018/11/13 Javascript
vue-loader中引入模板预处理器的实现
2019/09/04 Javascript
React中使用UMEditor的方法示例
2019/12/27 Javascript
Python内置函数的用法实例教程
2014/09/08 Python
对python 数据处理中的LabelEncoder 和 OneHotEncoder详解
2018/07/11 Python
Python读取excel指定列生成指定sql脚本的方法
2018/11/28 Python
python读取文件名并改名字的实例
2019/01/07 Python
使用python读取.text文件特定行的数据方法
2019/01/28 Python
Python3.4解释器用法简单示例
2019/03/22 Python
python 实现视频 图像帧提取
2019/12/10 Python
python:目标检测模型预测准确度计算方式(基于IoU)
2020/01/18 Python
Python调用接口合并Excel表代码实例
2020/03/31 Python
python中get和post有什么区别
2020/06/19 Python
python 实现全球IP归属地查询工具
2020/12/18 Python
sklearn中的交叉验证的实现(Cross-Validation)
2021/02/22 Python
香奈儿美国官网:CHANEL美国
2020/05/20 全球购物
用C语言实现文件读写操作
2013/10/27 面试题
纪录片信仰观后感
2015/06/08 职场文书
安全事故隐患排查治理制度
2015/08/05 职场文书
2016年教师节感恩寄语
2015/12/04 职场文书
小学科学课教学反思
2016/02/23 职场文书
jquery插件实现搜索历史
2021/04/24 jQuery
MySQL系列之十 MySQL事务隔离实现并发控制
2021/07/02 MySQL