讓前端程序更具可維護性，是一個老生常談的問題，大多數時候我們都關注於應用層面的代碼可維護性，如：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強力功能點如下：
- 樹形類命名空間組織
- 類子父關系的層次體系展示
- 成員與事件和配置項快速索引
- 可穿插着色代碼范例演示和編輯范例代碼
- 類成員源碼實現部分快速導航
- 很簡單一條命令可以將目錄下的js生成幫助手冊，推薦通過批處理文件操作
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：在文檔注釋中標記某個類或類成員的錨點。
文檔化你的項目不僅可以讓催悲的前端們將自己寫的注釋變更具有價值，也可以為項目后期維護帶來巨大便捷，在協同作戰環境下起着至關重要的作用。