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

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

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

JsDoc Toolkit不久前發(fā)布了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 指定參數(shù)名和說明來描述一個函數(shù)參數(shù)

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

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

下面我們來創(chuàng)建test下的js文件
簡單的方法標注
myjs.js

復制代碼代碼如下:

 
/** 
* @fileOverview 簡單的方法標注示例 
* @author <a href="llying.javaeye.com">llying</a> 
* @version 0.1 
*/ 

/** 
* @description 加法運算 
* @param {Num} num1 加數(shù) 
* @param {Num} num2 被加數(shù) 
* @return {Num} result 結果 
*/ 
function add(num1,num2){ 
return num1 + num2; 
} 
/** 
* @description 減法運算 
* @param {Num} num1 減數(shù) 
* @param {Num} num2 被減數(shù) 
* @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+"}"; 
} 
} 