【轉】Jsduck一個純淨的前端文檔生成神器

讓前端程序更具可維護性，是一個老生常談的問題，大多數時候咱們都關注於應用層面的代碼可維護性，如：OO、模塊化、MVC，編碼規範、可擴展和複用性，但這都是屬於設計層面須要考慮的事情，可維護性還應包含另外一個方面，也是不少coder容易忽略的地方，就是將本身寫的程序以文檔的形式沉澱起來，對本身工做有一個結構化的組織，也能夠幫助到他人。

試想一下以下狀況：
一、團隊中加入了新的同窗，這時他可能須要快速的將目前項目中現有程序有一個系統的瞭解，如：某個公共工具模塊的用途，某個通用組件的接口，程序之間的依賴性，這時他只有去看源碼和註釋了。
二、團隊中有同窗離開，但他寫的程序在此以前已經深刻到項目的各個層面，最瞭解和能快速修改維護這些程序的人可能只有他，以後在迭代時趕上其環節，其餘接手的同窗只能望眼欲穿了。
三、本身寫了一個不錯的可複用組件，打算推廣到團隊中，這時他人須要使用本身的組件時不得不去看源碼和註釋了。

這時候若是每一個人都對本身程序有一個文檔化的闡釋，即可對上述問題作出很大的緩解，一般程序的文檔化需求只存在於大型項目或是擁有成熟體系的框架之中，對於前端們來說其實大多數時候都想用文檔來展現和沉澱本身的知識成果的，可一直缺少一套行之有效快速一致性的解決方案，致使在你們談到程序文檔化的時候都由於時間關係，繁瑣程度就望而卻步了。

長期以來前端開發們都缺少一個像樣的文檔化工具，雖然在這以前出現過 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：在文檔註釋中標記某個類或類成員的錨點。

文檔化你的項目不只可讓催悲的前端們將本身寫的註釋變動具備價值，也能夠爲項目後期維護帶來巨大便捷，在協同做戰環境下起着相當重要的做用。