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 相关文章推荐
JavaScript使用prototype定义对象类型(转)[
Dec 22 Javascript
javascript通过navigator.userAgent识别各种浏览器
Oct 25 Javascript
代码获取历史上的今天发生的事
Apr 11 Javascript
JavaScript跨浏览器获取页面中相同class节点的方法
Mar 03 Javascript
JS替换字符串中空格方法
Apr 17 Javascript
多种jQuery绑定事件的实现方式
Jun 13 Javascript
BootStrap modal模态弹窗使用小结
Oct 26 Javascript
利用jquery实现下拉框的禁用与启用
Dec 07 Javascript
javascript 中null和undefined区分和比较
Apr 19 Javascript
微信小程序自定义toast实现方法详解【附demo源码下载】
Nov 28 Javascript
javascript按顺序加载运行js方法
Dec 01 Javascript
Element Badge标记的使用方法
Jul 27 Javascript
编写可维护面向对象的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
PHP4和PHP5性能测试和对比 测试代码与环境
2007/08/17 PHP
PHP extract 将数组拆分成多个变量的函数
2010/06/30 PHP
PHP实现的mysql主从数据库状态检测功能示例
2017/07/20 PHP
Laravel 读取 config 下的数据方法
2019/10/13 PHP
javascript StringBuilder类实现
2008/12/22 Javascript
JavaScript 轻松搞定快捷留言功能 只需一行代码
2010/04/01 Javascript
document.execCommand()的用法小结
2014/01/08 Javascript
JavaScript严格模式禁用With语句的原因
2014/10/20 Javascript
javascript实现可键盘控制的抽奖系统
2016/03/10 Javascript
jQuery 获取页面li数组并删除不在数组中的key
2016/08/02 Javascript
js实现右键菜单功能
2016/11/28 Javascript
详解node HTTP请求客户端 - Request
2017/05/05 Javascript
jQuery中each循环的跳出和结束实例
2017/08/16 jQuery
js实现会跳动的日历效果(完整实例)
2017/10/18 Javascript
vue自定义过滤器创建和使用方法详解
2017/11/06 Javascript
vue中动态设置meta标签和title标签的方法
2018/07/11 Javascript
vue实现文字加密功能
2019/09/27 Javascript
[01:10]DOTA2次级职业联赛 - Fly战队宣传片
2014/12/01 DOTA
详解设计模式中的工厂方法模式在Python程序中的运用
2016/03/02 Python
基于python实现的抓取腾讯视频所有电影的爬虫
2016/04/22 Python
python的几种矩阵相乘的公式详解
2019/07/10 Python
Pycharm使用之设置代码字体大小和颜色主题的教程
2019/07/12 Python
python PyQt5/Pyside2 按钮右击菜单实例代码
2019/08/17 Python
关于Pytorch的MNIST数据集的预处理详解
2020/01/10 Python
html5中为audio标签增加停止按钮动作实现方法
2013/01/04 HTML / CSS
财务管理个人自荐书范文
2013/11/24 职场文书
支教自我鉴定
2014/01/18 职场文书
银行办公室岗位职责
2014/03/10 职场文书
临床医师个人自我评价
2014/04/06 职场文书
2014离婚协议书范文(3篇)
2014/11/29 职场文书
年会邀请函范文
2015/01/30 职场文书
2015年综治宣传月活动总结
2015/03/25 职场文书
2015年财政局工作总结
2015/05/21 职场文书
2016年清明节寄语
2015/12/04 职场文书
十大经典日本动漫排行榜 海贼王第三,犬夜叉仅第八
2022/03/18 日漫
javascript进阶篇深拷贝实现的四种方式
2022/07/07 Javascript