JSDoc 介绍使用规范JsDoc的使用介绍
javaer 2011-04-18
JsDoc Toolkit不久前发布了2.3.2版本，主要还是对前版本的修复。
如果你需要使用Ant，JsDoc还有一个Ant插件：JsDocToolkitAntTask
下载JsDocToolkit2.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-jarjsrun.jarapp/run.js-a-e=GB18030-t=templates/jsdoctest/*.js
当然如果感觉通过命令行的方式比较麻烦，我们可以自行创建一个.bat文件
将上面的内容复制到该文件中，执行即可。
下面我来简单解释一下这其中的参数
-a表示全部的方法
-e表示对应的文件的编码根式这里对应的是GB18030默认的是utf-8
-t表示生产doc的文档样式模板
这里的test/*.js表示在test目录下的全部javascript文件
执行完毕后将文档结果默认输出到/out/jsdoc目录下。当然这个目录也是可以定义的
具体参数可以使用
java-jarjsrun.jarapp/run.js--help
进行查看。
结果如下：
复制代码代码如下:
OPTIONS:
-aor--allfunctions
Includeallfunctions,evenundocumentedones.
-cor--conf
Loadaconfigurationfile.
-d=<PATH>or--directory=<PATH>
Outputtothisdirectory(defaultsto"out").
-D="myVar:Myvalue"or--define="myVar:Myvalue"
Multiple.Defineavariable,availableinJsDocasJSDOC.opt.D.myVar.
-e=<ENCODING>or--encoding=<ENCODING>
Usethisencodingtoreadandwritefiles.
-E="REGEX"or--exclude="REGEX"
Multiple.Excludefilesbasedonthesuppliedregex.
-hor--help
Showthismessageandexit.
-nor--nocode
Ignoreallcode,onlydocumentcommentswith@nametags.
-o=<PATH>or--out=<PATH>
Printlogmessagestoafile(defaultstostdout).
-por--private
Includesymbolstaggedasprivate,underscoredandinnersymbols.
-qor--quiet
Do not output any messages, not even warnings.下面我们来创建test下的js文件
简单的方法标注
myjs.js
复制代码代码如下:
/**
*@fileOverview简单的方法标注示例
*@version0.1
*//**
*@description加法运算
*@param{Num}num1加数
*@param{Num}num2被加数
*@return{Num}result结果
*/
functionadd(num1,num2){
returnnum1+num2;
}
/**
*@description减法运算
*@param{Num}num1减数
*@param{Num}num2被减数
*@return{Num}result结果
*/
functionminus(num1,num2){
returnnum1-num2;
}类的方法标注
myjs2.js
复制代码代码如下:
/**
*@fileOverview简单的类对象标注示例
*@version0.1
*/
/**
*@authorllying
*@constructorPerson
*@description一个Person类
*@seeThe<ahref="#">llying</a>.
*@examplenewParent(“张三”,15);
*@sinceversion0.1
*@param{String}username姓名
*@param{Num}age年龄
*/
functionPerson(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格式
*@seePerson#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
