快捷導(dǎo)航

JSDoc 介紹使用規(guī)范JsDoc的使用介紹

更新時(shí)間：2011年02月12日 20:34:45 作者：

JsDoc Toolkit 是一個(gè)把js描述格式化成文檔的工具。開(kāi)發(fā)者只需按JsDoc的規(guī)范寫(xiě)好注釋就可以很方便導(dǎo)出文檔。它是google 推薦的 JsDoc生成工具。

JsDoc Toolkit不久前發(fā)布了2.3.2版本，主要還是對(duì)前版本的修復(fù)。
如果你需要使用Ant，JsDoc還有一個(gè)Ant插件：JsDoc Toolkit Ant Task
下載JsDoc Toolkit2.3.2：http://jsdoc-toolkit.googlecode.com/files/jsdoc_toolkit-2.3.2.zip
命令名描述
@param @argument 指定參數(shù)名和說(shuō)明來(lái)描述一個(gè)函數(shù)參數(shù)

@returns 描述函數(shù)的返回值
@author 指示代碼的作者
@deprecated 指示一個(gè)函數(shù)已經(jīng)廢棄，而且在將來(lái)的代碼版本中將徹底刪除。要避免使用這段代碼
@see 創(chuàng)建一個(gè)HTML鏈接，指向指定類的描述
@version 指定發(fā)布版本
@requires 創(chuàng)建一個(gè)HTML鏈接，指向這個(gè)類所需的指定類
@throws @exception 描述函數(shù)可能拋出的異常的類型
{@link} 創(chuàng)建一個(gè)HTML鏈接，指向指定的類。這與@see很類似，但{@link}能嵌在注釋文本中
@fileoverview 這是一個(gè)特殊的標(biāo)記。如果在文件的第一個(gè)文檔塊中使用這個(gè)標(biāo)記，則指定該文檔塊的余下部分將用來(lái)提供這個(gè)文件的概述
@class 提供類的有關(guān)信息，用在構(gòu)造函數(shù)的文檔中
@constructor 明確一個(gè)函數(shù)是某個(gè)類的構(gòu)造函數(shù)
@type 指定函數(shù)的返回類型
@extends 指示一個(gè)類派生了另一個(gè)類。JSDoc通常自己就可以檢測(cè)出這種信息，不過(guò)，在某些情況下則必須使用這個(gè)標(biāo)記
@private 指示一個(gè)類或函數(shù)是私有的。私有類和函數(shù)不會(huì)出現(xiàn)在HTML文檔中，除非運(yùn)行JSDoc時(shí)提供了--private命令行選項(xiàng)
@final 指示一個(gè)值是常量值。要記住JavaScript無(wú)法真正保證一個(gè)值是常量
@ignore JSDoc忽略有這個(gè)標(biāo)記的函數(shù)

JsDoc:是js文檔生成工具，它從javascript程序源代碼中抽取類、方法、成員等注釋信息形成一個(gè)和源代碼配套的API幫助文檔。
Java開(kāi)源項(xiàng)目http://www.jsdoctoolkit.org/，它是一個(gè)功能強(qiáng)大的javascript文檔生成工具。
下面我們來(lái)結(jié)束一下如何使用。
我們通過(guò)下載工具類庫(kù)。
這里我們使用的是jsdoc_toolkit-2.1.0.zip也是當(dāng)前的最高版本。
我們將這個(gè)文件解壓?？梢钥吹嚼锩鍾EADME.txt文件。
這里有詳細(xì)的使用說(shuō)明?！竞孟窠榻B到這里就可以了。當(dāng)然你也可以繼續(xù)讀下】
這里我們需要通過(guò)命令行進(jìn)行創(chuàng)建javascript文檔。
java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js
當(dāng)然如果感覺(jué)通過(guò)命令行的方式比較麻煩，我們可以自行創(chuàng)建一個(gè).bat文件
將上面的內(nèi)容復(fù)制到該文件中，執(zhí)行即可。
下面我來(lái)簡(jiǎn)單解釋一下這其中的參數(shù)
-a 表示全部的方法
-e 表示對(duì)應(yīng)的文件的編碼根式這里對(duì)應(yīng)的是GB18030 默認(rèn)的是utf-8
-t 表示生產(chǎn)doc的文檔樣式模板
這里的test/*.js表示在test目錄下的全部javascript文件
執(zhí)行完畢后將文檔結(jié)果默認(rèn)輸出到/out/jsdoc目錄下。當(dāng)然這個(gè)目錄也是可以定義的
具體參數(shù)可以使用
java -jar jsrun.jar app/run.js --help
進(jìn)行查看。
結(jié)果如下：

復(fù)制代碼代碼如下:

 
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. 

下面我們來(lái)創(chuàng)建test下的js文件
簡(jiǎn)單的方法標(biāo)注
myjs.js

復(fù)制代碼代碼如下:

 
/** 
* @fileOverview 簡(jiǎn)單的方法標(biāo)注示例 
* @author <a href="llying.javaeye.com">llying</a> 
* @version 0.1 
*/ 

/** 
* @description 加法運(yùn)算 
* @param {Num} num1 加數(shù) 
* @param {Num} num2 被加數(shù) 
* @return {Num} result 結(jié)果 
*/ 
function add(num1,num2){ 
return num1 + num2; 
} 
/** 
* @description 減法運(yùn)算 
* @param {Num} num1 減數(shù) 
* @param {Num} num2 被減數(shù) 
* @return {Num} result 結(jié)果 
*/ 
function minus(num1,num2){ 
return num1 - num2; 
} 

類的方法標(biāo)注
myjs2.js

復(fù)制代碼代碼如下:

 
/** 
* @fileOverview 簡(jiǎn)單的類對(duì)象標(biāo)注示例 
* @author <a href="llying.javaeye.com">llying</a> 
* @version 0.1 
*/ 
/** 
* @author llying 
* @constructor Person 
* @description 一個(gè)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內(nèi)容 
* @param {String} content 內(nèi)容 
*/ 
this.say = function(content) 
{ 
alert(this.username+" say :"+content); 
} 
/** 
* @description 返回json格式的對(duì)象 
* @return {String} json格式 
* @see Person#say 
*/ 
this.getJson = function(){ 
return "{name:"+this.username+",age"+this.age+"}"; 
} 
} 