讓前端程序更具可維護性，是一個老生常談的問題，大多數時候我們都關注於應用層面的代碼可維護性，如：OO、模塊化、MVC，編碼規範、可擴展和複用性，但這都是屬於設計層面需要考慮的事情，可維護性還應包含另一個方面，也是很多coder容易忽略的地方，就是將自己寫的程序以文檔的形式沉澱起來，對自己工作有一個結構化的組織，也可以幫助到他人。
- 試想一下如下情況：
- 1、團隊中加入了新的同學，這時他可能需要快速的將目前項目中現有程序有一個系統的瞭解，如：某個公共工具模塊的用途，某個通用組件的接口，程序之間的依賴性，這時他只有去看源碼和註釋了。
- 2、團隊中有同學離開，但他寫的程序在此之前已經深入到項目的各個層面，最瞭解和能快速修改維護這些程序的人可能只有他，之後在迭代時遇上其環節，其他接手的同學只能望眼欲穿了。
- 3、自己寫了一個不錯的可複用組件，打算推廣到團隊中，這時他人需要使用自己的組件時不得不去看源碼和註釋了。
這時候如果每個人都對自己程序有一個文檔化的闡釋，便可對上述問題做出很大的緩解，通常程序的文檔化需求只存在於大型項目或是擁有成熟體系的框架之中，對於前端們來講其實大多數時候都想用文檔來展示和沉澱自己的知識成果的，可一直缺乏一套行之有效快速一致性的解決方案，導致在大家談到程序文檔化的時候都因爲時間關係，繁瑣程度就望而卻步了。
長期以來前端開發們都缺乏一個像樣的文檔化工具，雖然在這之前出現過 YUI DOC、JSDoc ，但這些工具始終難於將開發者從複雜的配置中解脫出來，從而使開發者很快便將它們遺忘。
如果有對sencha的 ExtJs 和 Sencha Touch 開發框架有過了解的同學想必都對爲其定製的API文檔印象深刻，富應用形態的展現方式和樹節點的命名空間管理， 避免了YUI DOC 和 jQeury API 那樣沉長頁面帶來的繁瑣，而文檔中附加的學習的範例也能幫助初學者儘快上手，生成這樣強大的 API 文檔使用的是 jsduck，它不僅在使用和配置上非常簡單，文檔的 UI 和交互方式也是目前對於開發者來說是最友好的。
jsduck 是 senchalabs 衆多開源項目中的一個，它是使用 ruby 編寫的 JS API 文檔生成器。
Jsduck功能點如下：
1、樹形類命名空間組織；
2、類子父關係的層次體系展示；
3、成員與事件和配置項快速索引；
4、可穿插着色代碼範例演示和編輯範例代碼；
5、類成員源碼實現部分快速導航；
在Windows下安裝jsduck：
首先在github 上下載最新版的二進制版本，下載之後只有一個exe文件，此文件中已捆綁好了ruby解釋器，不需要另外獨立安裝，將下載後的文件更名爲jsduck.exe，在windows的環境變量的PATH變量中添加上此文件的路徑，這樣在命令行下輸入jsduck便可可以直接調用到jsduck.exe。
使用jsduck ，在windows命令行中輸入：
- jsduck –builtin-classes sencha\senchalabs\jsfile\ –output=sencha\senchalabs\doc\ –encoding=gbk –images= sencha\senchalabs\images
如果不出意外你將在輸出的目錄中看到生成的文件了，目錄中有一個index.html文件這便是文檔的入口，在你的瀏覽器中打開它。
命令中“–”開頭的爲命令的參數，以下是一些常用的命令
- –builtin-classes：構建javascript語言內建類文檔，如Array或Object類的使用說明。
- –output：文檔輸出所在目錄。
- –encoding：編碼默認爲utf-8，如果js文件中包含了中文字符設置gbk即可。
- –welcome:爲一個html文件的路徑，文件中的內容會被解析出來放到文檔的歡迎頁顯示。
- –eg-iframe：配置一個html文件路徑，這個html文件用來配置@example範例的預覽方式，如需要生成非ExtJs或者sencha touch項目的話通常都需要自定義配置。
- –images：如果文檔中引入了圖片需配置一個圖片目錄。
- –title：自定義文檔的標題
- –footer：自定義文檔腳註
- –help：full 顯示幫助文檔。
另外還有一個–config參數用來配置文檔生成的命令集合，它的值是一個json配置文件的路徑。
創建一個config.json文件
- {
- "–output":"sencha/senchalabs/doc/",
- "–encoding":"gbk",
- "–":["sencha/senchalabs/jsfile/"],
- "–eg-iframe":"sencha/senchalabs/eg-iframe.html",
- "–welcome":"sencha/senchalabs/welcome.html",
- "–images":"sencha/senchalabs/images"
- }
在命令行中輸入
- jsduck –builtin-classes –config=config.json
實現的效果和第一個例子中是一樣的，不過使用config.json的方式更加容易維護。
稍加留意會發現實際上文檔的生成方式完全是基於文件中註釋裏面的 @tag 標籤的，和 jsdoc 使用的標籤規範是一樣的。
註釋規範需以“/**” 開頭和“*/”結束，在 eclipse 或者 Aptana 這類支持 javaDoc 或 jsDoc 的 IDE 中鍵入 “/**” 按下回車鍵即可生成一個符合文檔生標準的註釋塊，如果使用 SpketIDE，註釋塊生成的時候還能幫助開發者自動完成函數參數的命名
以下是一些常用標籤的註解：
- @author：作者
- @class：類
- @deprecated：標記此方法屬性或者類不贊成使用，在升級過渡的時候需兼容之前的API時特別有用。
- @example：給類或者方法添加一個代碼範例，jsduck不僅會給代碼着色，還能給代碼生成一個代碼編輯器，編輯代碼後可實時預覽，使用@example需要四個空格的縮進。
- @extends：標記一個類繼承自另一個類，生成後會有一個類型繼承體系陳列在文檔視圖的右側。
- @cfg：構造器的配置項，並在其後跟隨“{className}”，再跟隨參數名。
- 範例：@cfg {String} fieldName配置項的描述。
- @return：與@cfg類似，標記一個函數成員調用過後的返回類型。
- 範例：@return {Number} 文字描述
- @param：與@cfg類似，給一個函數成員標記其所需的參數類型和描述，如果參數類型爲多種可以用“/”分割，如需要給參數進行更詳細描述還能使用“[param.member]”描述符。
- 範例：@param {Number/String} fieldName
- 範例：@param {String[]} fieldName
- 範例： /**
- * @cfg {Object} opt
- * @cfg {Number} [opt.age]
- * @cfg {Number} [opt.name=0]
- */
- @event：標記一個事件，隨後通常會跟隨@param標籤給事件回調函數聲明參數的說明。
- @inheritdoc：在其後跟隨Class#member，常用在子類覆蓋父類成員後，子類註釋塊還需繼續使用父類註釋的情況下使用。
- @private：將成員標記成私有，雖然也有@public但如果不特殊標明即爲公有。
- @protected：將成員標記成受保護的。
- @static:將成員標記成靜態的，靜態成員也會在文檔中進行分類展示。
- @img：在文檔註釋中鏈接一張圖片，讓文檔變得更具可讀性。
- @link：在文檔註釋中標記某個類或類成員的錨點。
文檔化你的項目不僅可以讓催悲的前端們將自己寫的註釋變更具有價值，也可以爲項目後期維護帶來巨大便捷，在協同作戰環境下起着至關重要的作用。