jsdoc toolkit - a jsdoc tool for Java developer

原始發表時間：2010-02-20

    早有耳聞jsdoc的大名，但是最近才下決心要把js程式碼文件化，因為想讓一份js程式碼更好的為team所用，進一步發展，沒有好的文件，幾乎很難實現。

    首先得安裝使用jsdoc工具的環境，在網上找到兩篇文章“http://caterpillar.onlyfun.net/Gossip/AjaxGossip/InstallJSDoc.html ”和“http://jsdoc.sourceforge.net/#install ”，但按這兩篇文章的說明，要安裝Perl環境，接著用jsdoc的perl指令碼來生成js程式碼的文件，總感覺十分別扭（畢竟一直在windows下用java開發，很少使用perl語言）。

    後來發現了Google早就有的jsdoc toolkit（這是個用java開發的生成jsdoc的jar工具包），下載連結是“http://code.google.com/p/jsdoc-toolkit/downloads/list ”，下載最新的2.3.3-beta版，將該zip包解壓到目錄“E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\”中，在該目錄中有幾個資料夾和檔案，關鍵目錄名有app和templates，關鍵的檔案則有jsrun.jar和README.txt。

    首先閱讀官方的文件README.txt中，其中“RUNNING VIA SHELL SCRIPT”的段落甚為有用，按照其說明編寫命令列指令碼如下：

    java -jar E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ jsrun.jar E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ app\run.js -t=E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ templates\jsdoc\ -p -r=4 -u E:\work_eclipse\workspace_JDK1.5\webim\ webcontent\js\

    執行環境是jdk1.6.x，jsdoc toolkit 2.3.3-beta

    從上面指令碼的下劃線文字中可以看出——應用專案為webim，其js存放在專案下的相對目錄 webcontent\js 中，在命令列中執行該指令碼，就會在目錄 E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ out\jsdoc\ 中生成js程式碼的jsdoc文件——分別是兩個檔案（名為index.html、files.html）和一個目錄（名為symbols），雙擊index.html就能看到對應js的文件了，格式跟javadoc非常相近。

    但是起初我遇到一個問題，就是所有的js類的方法都歸到了_global_ 這個類下面，各個類名沒有在Class Index中列舉出來，後來檢視了Google官方的TagReference（文章底部的附加資料中有相關連結），才知道是js程式碼中沒有加入@class標記，導致jsdoc沒有識別出來哪些是類程式碼的註釋，加上@class後，再次生成jsdoc即可。

附加資料：

1. jsdoc toolkit 部分引數說明，可以參見《JsDoc Toolkit 簡介》“http://www.zhuoqun.net/html/y2009/1363.html ”
   
2. js程式碼中jsdoc編寫規範，可以檢視連結“http://code.google.com/p/jsdoc-toolkit/wiki/TagReference ”