JSDoc 介紹使用規(guī)范JsDoc的使用介紹
更新時間：2011年02月12日 20:34:45 作者：
JsDoc Toolkit 是一個把js描述格式化成文檔的工具。開發(fā)者只需按JsDoc的規(guī)范寫好注釋就可以很方便導(dǎo)出文檔。它是google 推薦的 JsDoc生成工具。
JsDoc Toolkit不久前發(fā)布了2.3.2版本，主要還是對前版本的修復(fù)。
如果你需要使用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 這是一個特殊的標(biāo)記。如果在文件的第一個文檔塊中使用這個標(biāo)記，則指定該文檔塊的余下部分將用來提供這個文件的概述
@class 提供類的有關(guān)信息，用在構(gòu)造函數(shù)的文檔中
@constructor 明確一個函數(shù)是某個類的構(gòu)造函數(shù)
@type 指定函數(shù)的返回類型
@extends 指示一個類派生了另一個類。JSDoc通常自己就可以檢測出這種信息，不過，在某些情況下則必須使用這個標(biāo)記
@private 指示一個類或函數(shù)是私有的。私有類和函數(shù)不會出現(xiàn)在HTML文檔中，除非運行JSDoc時提供了--private命令行選項
@final 指示一個值是常量值。要記住JavaScript無法真正保證一個值是常量
@ignore JSDoc忽略有這個標(biāo)記的函數(shù)
JsDoc:是js文檔生成工具，它從javascript程序源代碼中抽取類、方法、成員等注釋信息形成一個和源代碼配套的API幫助文檔。
Java開源項目http://www.jsdoctoolkit.org/，它是一個功能強(qiáng)大的javascript文檔生成工具。
下面我們來結(jié)束一下如何使用。
我們通過下載工具類庫。
這里我們使用的是jsdoc_toolkit-2.1.0.zip也是當(dāng)前的最高版本。
我們將這個文件解壓?？梢钥吹嚼锩鍾EADME.txt文件。
這里有詳細(xì)的使用說明。【好像介紹到這里就可以了。當(dāng)然你也可以繼續(xù)讀下】
這里我們需要通過命令行進(jìn)行創(chuàng)建javascript文檔。
java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js
當(dāng)然如果感覺通過命令行的方式比較麻煩，我們可以自行創(chuàng)建一個.bat文件
將上面的內(nèi)容復(fù)制到該文件中，執(zhí)行即可。
下面我來簡單解釋一下這其中的參數(shù)
-a 表示全部的方法
-e 表示對應(yīng)的文件的編碼根式 這里對應(yīng)的是GB18030 默認(rèn)的是utf-8
-t 表示生產(chǎn)doc的文檔樣式模板
這里的test/*.js表示在test目錄下的全部javascript文件
執(zhí)行完畢后將文檔結(jié)果默認(rèn)輸出到/out/jsdoc目錄下。當(dāng)然這個目錄也是可以定義的
具體參數(shù)可以使用
java -jar jsrun.jar app/run.js --help
進(jìn)行查看。
結(jié)果如下：
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文件
簡單的方法標(biāo)注
myjs.js
/**
* @fileOverview 簡單的方法標(biāo)注示例
* @author <a href="llying.javaeye.com">llying</a>
* @version 0.1
*/
/**
* @description 加法運算
* @param {Num} num1 加數(shù)
* @param {Num} num2 被加數(shù)
* @return {Num} result 結(jié)果
*/
function add(num1,num2){
return num1 + num2;
}
/**
* @description 減法運算
* @param {Num} num1 減數(shù)
* @param {Num} num2 被減數(shù)
* @return {Num} result 結(jié)果
*/
function minus(num1,num2){
return num1 - num2;
}
類的方法標(biāo)注
myjs2.js
/**
* @fileOverview 簡單的類對象標(biāo)注示例
* @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內(nèi)容
* @param {String} content 內(nèi)容
*/
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+"}";
}
}
現(xiàn)在我們可以運行java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js
至此我們的js文檔生成完畢。我們也無需羨慕JavaDoc了。
我們只是列出了常用的標(biāo)簽，至于更多的可以登陸到官方網(wǎng)站查看
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 指定參數(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 這是一個特殊的標(biāo)記。如果在文件的第一個文檔塊中使用這個標(biāo)記，則指定該文檔塊的余下部分將用來提供這個文件的概述
@class 提供類的有關(guān)信息，用在構(gòu)造函數(shù)的文檔中
@constructor 明確一個函數(shù)是某個類的構(gòu)造函數(shù)
@type 指定函數(shù)的返回類型
@extends 指示一個類派生了另一個類。JSDoc通常自己就可以檢測出這種信息，不過，在某些情況下則必須使用這個標(biāo)記
@private 指示一個類或函數(shù)是私有的。私有類和函數(shù)不會出現(xiàn)在HTML文檔中，除非運行JSDoc時提供了--private命令行選項
@final 指示一個值是常量值。要記住JavaScript無法真正保證一個值是常量
@ignore JSDoc忽略有這個標(biāo)記的函數(shù)
JsDoc:是js文檔生成工具，它從javascript程序源代碼中抽取類、方法、成員等注釋信息形成一個和源代碼配套的API幫助文檔。
Java開源項目http://www.jsdoctoolkit.org/，它是一個功能強(qiáng)大的javascript文檔生成工具。
下面我們來結(jié)束一下如何使用。
我們通過下載工具類庫。
這里我們使用的是jsdoc_toolkit-2.1.0.zip也是當(dāng)前的最高版本。
我們將這個文件解壓?？梢钥吹嚼锩鍾EADME.txt文件。
這里有詳細(xì)的使用說明。【好像介紹到這里就可以了。當(dāng)然你也可以繼續(xù)讀下】
這里我們需要通過命令行進(jìn)行創(chuàng)建javascript文檔。
java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js
當(dāng)然如果感覺通過命令行的方式比較麻煩，我們可以自行創(chuàng)建一個.bat文件
將上面的內(nèi)容復(fù)制到該文件中，執(zhí)行即可。
下面我來簡單解釋一下這其中的參數(shù)
-a 表示全部的方法
-e 表示對應(yīng)的文件的編碼根式 這里對應(yīng)的是GB18030 默認(rèn)的是utf-8
-t 表示生產(chǎn)doc的文檔樣式模板
這里的test/*.js表示在test目錄下的全部javascript文件
執(zhí)行完畢后將文檔結(jié)果默認(rèn)輸出到/out/jsdoc目錄下。當(dāng)然這個目錄也是可以定義的
具體參數(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.
下面我們來創(chuàng)建test下的js文件
簡單的方法標(biāo)注
myjs.js
復(fù)制代碼 代碼如下:
/**
* @fileOverview 簡單的方法標(biāo)注示例
* @author <a href="llying.javaeye.com">llying</a>
* @version 0.1
*/
/**
* @description 加法運算
* @param {Num} num1 加數(shù)
* @param {Num} num2 被加數(shù)
* @return {Num} result 結(jié)果
*/
function add(num1,num2){
return num1 + num2;
}
/**
* @description 減法運算
* @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 簡單的類對象標(biāo)注示例
* @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內(nèi)容
* @param {String} content 內(nèi)容
*/
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+"}";
}
}
現(xiàn)在我們可以運行java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js
至此我們的js文檔生成完畢。我們也無需羨慕JavaDoc了。
我們只是列出了常用的標(biāo)簽，至于更多的可以登陸到官方網(wǎng)站查看
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
您可能感興趣的文章:
- JSP 2.1和JSF 1.2規(guī)范發(fā)布預(yù)覽版本
- js 編寫規(guī)范
- Javascript模塊化編程(一)AMD規(guī)范(規(guī)范使用模塊)
- Java Web項目前端規(guī)范(采用命名空間使js深度解耦合)
- AMD異步模塊定義介紹和Require.js中使用jQuery及jQuery插件的方法
- Node.js編碼規(guī)范
- PowerShell中使用Get-Alias命令獲取cmdlet別名例子
- C#調(diào)用CMD命令實例
- Windows Powershell 命令集 cmdlets
- PHP中執(zhí)行cmd命令的方法
- PHP啟動windows應(yīng)用程序、執(zhí)行bat批處理、執(zhí)行cmd命令的方法(exec、system函數(shù)詳解)
- java執(zhí)行windows下cmd命令的方法
- bat/cmd批處理連接SqlServer數(shù)據(jù)庫查詢腳本
- Python使用CMD模塊更優(yōu)雅的運行腳本
- CMD命令行中以管理員權(quán)限啟動應(yīng)用程序?qū)崿F(xiàn)方法
- C#隱式運行CMD命令（隱藏命令窗口）
- JavaScript模塊規(guī)范之AMD規(guī)范和CMD規(guī)范
- JsDoc 基于java的js文檔生成工具
相關(guān)文章
這篇文章介紹了仿百度輸入框智能提示的js代碼，有需要的朋友可以參考一下2013-08-08
這篇文章主要介紹了微信小程序掃描二維碼獲取信息，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2019-05-05
這篇文章主要為大家詳細(xì)介紹了JavaScript貪吃蛇的實現(xiàn)代碼，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價值，感興趣的小伙伴們可以參考一下2021-09-09
這篇文章主要介紹了淺談如何優(yōu)雅處理JavaScript異步錯誤，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2019-11-11
這篇文章主要介紹了js獲取今天、昨天、明天的日期函數(shù)代碼,需要的朋友可以參考下2023-05-05
JavaScript中無法通過div.style.left獲取值的解決方法
這篇文章主要介紹了JavaScript中無法通過div.style.left獲取值的問題分析及解決方法,需要的朋友可以參考下2017-02-02
js處理json格式的插入、修改、刪除，以及字符串的比較等常用操作，下面有五個示例，感興趣的朋友可以學(xué)習(xí)下2013-09-09
JavaScript toDataURL圖片轉(zhuǎn)換問題解讀
這篇文章主要介紹了JavaScript toDataURL圖片轉(zhuǎn)換問題，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2023-06-06
代碼觸發(fā)js事件(click、change)示例應(yīng)用
Chrome , Firfox 不支持fireEvent的方法可以使用dispatchEvent的方法替代，直接給一個兼容的Code，下面有個不錯的示例，喜歡的朋友可以收藏下2013-12-12
Uni-App用uView組件庫中u-picker實現(xiàn)地區(qū)的省-市-區(qū)三級聯(lián)動、確認(rèn)及回顯
最近項目要使用uni-app遇到省市縣三級聯(lián)動的問題,下面這篇文章主要給大家介紹了關(guān)于Uni-App用uView組件庫中u-picker實現(xiàn)地區(qū)的省-市-區(qū)三級聯(lián)動、確認(rèn)及回顯的相關(guān)資料,需要的朋友可以參考下2023-12-12