讓前端程式更具可維護性，是一個老生常談的問題，大多數時候我們都關註於應用層面的代碼可維護性，如：OO、模塊化、MVC，編碼規範、可擴展和復用性，但這都是屬於設計層面需要考慮的事情，可維護性還應包含另一個方面，也是很多coder容易忽略的地方，就是將自己寫的程式以文檔的形式沉澱起來，對自己工作有一個結 ...
讓前端程式更具可維護性，是一個老生常談的問題，大多數時候我們都關註於應用層面的代碼可維護性，如：OO、模塊化、MVC，編碼規範、可擴展和復用性，但這都是屬於設計層面需要考慮的事情，可維護性還應包含另一個方面，也是很多coder容易忽略的地方，就是將自己寫的程式以文檔的形式沉澱起來，對自己工作有一個結構化的組織，也可以幫助到他人。
試想一下如下情況：
1、團隊中加入了新的同學，這時他可能需要快速的將目前項目中現有程式有一個系統的瞭解，如：某個公共工具模塊的用途，某個通用組件的介面，程式之間的依賴性，這時他只有去看源碼和註釋了。
2、團隊中有同學離開，但他寫的程式在此之前已經深入到項目的各個層面，最瞭解和能快速修改維護這些程式的人可能只有他，之後在迭代時遇上其環節，其他接手的同學只能望眼欲穿了。
3、自己寫了一個不錯的可復用組件，打算推廣到團隊中，這時他人需要使用自己的組件時不得不去看源碼和註釋了。
這時候如果每個人都對自己程式有一個文檔化的闡釋，便可對上述問題做出很大的緩解，通常程式的文檔化需求只存在於大型項目或是擁有成熟體系的框架之中，對於前端們來講其實大多數時候都想用文檔來展示和沉澱自己的知識成果的，可一直缺乏一套行之有效快速一致性的解決方案，導致在大家談到程式文檔化的時候都因為時間關係，繁瑣程度就望而卻步了。
長期以來前端開發們都缺乏一個像樣的文檔化工具，雖然在這之前出現過 YUI DOC、JSDoc ，但這些工具始終難於將開發者從複雜的配置中解脫出來，從而使開發者很快便將它們遺忘。
如果有對sencha的 ExtJs 和 Sencha Touch 開發框架有過瞭解的同學想必都對為其定製的API文檔印象深刻，富應用形態的展現方式和樹節點的命名空間管理， 避免了 YUI DOC 和 jQeury API 那樣沉長頁面帶來的繁瑣，而文檔中附加的學習的範例也能幫助初學者儘快上手，生成這樣強大的 API 文檔使用的是jsduck，它不僅在使用和配置上非常簡單，文檔的 UI 和交互方式也是目前對於開發者來說是最友好的。
1. Jsduck 簡介
jsduck 是 senchalabs 眾多開源項目中的一個，它是使用 ruby 編寫的 javascript API 文檔生成器。
Jsduck強力功能點如下：
- 樹形類命名空間組織
- 類子父關係的層次體系展示
- 成員與事件和配置項快速索引
- 可穿插著色代碼範例演示和編輯範例代碼
- 類成員源碼實現部分快速導航
2. 安裝jsduck
首先在github 上下載最新版的二進位版本，下載之後只有一個exe文件，此文件中已捆綁好了ruby解釋器，不需要另外獨立安裝，將下載後的文件更名為jsduck.exe，在windows的環境變數的PATH變數中添加上此文件的路徑，這樣在命令行下輸入jsduck便可可以直接調用到jsduck.exe。
註釋規範需以“/**” 開頭和“*/”結束，在 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：在文檔註釋中標記某個類或類成員的錨點。
文檔化你的項目不僅可以讓催悲的前端們將自己寫的註釋變更具有價值，也可以為項目後期維護帶來巨大便捷，在協同作戰環境下起著至關重要的作用。
