JSDoc 介绍使用规范JsDoc的使用介绍
更新时间：2011年02月12日 20:34:45 作者：
JsDoc Toolkit 是一个把js描述格式化成文档的工具。开发者只需按JsDoc的规范写好注释就可以很方便导出文档。它是google 推荐的 JsDoc生成工具。
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了。
我们只是列出了常用的标签，至于更多的可以登陆到官方网站查看
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
如果你需要使用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了。
我们只是列出了常用的标签，至于更多的可以登陆到官方网站查看
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
您可能感兴趣的文章:
- JSP 2.1和JSF 1.2规范发布预览版本
- js 编写规范
- Javascript模块化编程(一)AMD规范(规范使用模块)
- Java Web项目前端规范(采用命名空间使js深度解耦合)
- AMD异步模块定义介绍和Require.js中使用jQuery及jQuery插件的方法
- Node.js编码规范
- PowerShell中使用Get-Alias命令获取cmdlet别名例子
- C#调用CMD命令实例
- Windows Powershell 命令集 cmdlets
- PHP中执行cmd命令的方法
- PHP启动windows应用程序、执行bat批处理、执行cmd命令的方法(exec、system函数详解)
- java执行windows下cmd命令的方法
- bat/cmd批处理连接SqlServer数据库查询脚本
- Python使用CMD模块更优雅的运行脚本
- CMD命令行中以管理员权限启动应用程序实现方法
- C#隐式运行CMD命令（隐藏命令窗口）
- JavaScript模块规范之AMD规范和CMD规范
- JsDoc 基于java的js文档生成工具
相关文章
这篇文章介绍了仿百度输入框智能提示的js代码，有需要的朋友可以参考一下2013-08-08
这篇文章主要介绍了微信小程序扫描二维码获取信息，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2019-05-05
这篇文章主要为大家详细介绍了JavaScript贪吃蛇的实现代码，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2021-09-09
这篇文章主要介绍了浅谈如何优雅处理JavaScript异步错误，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2019-11-11
这篇文章主要介绍了js获取今天、昨天、明天的日期函数代码,需要的朋友可以参考下2023-05-05
JavaScript中无法通过div.style.left获取值的解决方法
这篇文章主要介绍了JavaScript中无法通过div.style.left获取值的问题分析及解决方法,需要的朋友可以参考下2017-02-02
js处理json格式的插入、修改、删除，以及字符串的比较等常用操作，下面有五个示例，感兴趣的朋友可以学习下2013-09-09
这篇文章主要介绍了JavaScript toDataURL图片转换问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2023-06-06
Chrome , Firfox 不支持fireEvent的方法可以使用dispatchEvent的方法替代，直接给一个兼容的Code，下面有个不错的示例，喜欢的朋友可以收藏下2013-12-12
Uni-App用uView组件库中u-picker实现地区的省-市-区三级联动、确认及回显
最近项目要使用uni-app遇到省市县三级联动的问题,下面这篇文章主要给大家介绍了关于Uni-App用uView组件库中u-picker实现地区的省-市-区三级联动、确认及回显的相关资料,需要的朋友可以参考下2023-12-12
最新评论