【轉】Jsduck:前端文檔產生利器Jsduck介紹及安裝使用

標籤：

讓前端程式更具可維護性，是一個老生常談的問題，大多數時候我們都關注於應用程式層面的代碼可維護性，如：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：在文檔注釋中標記某個類或類成員的錨點。

文檔化你的項目不僅可以讓催悲的前端們將自己寫的注釋變更具有價值，也可以為項目後期維護帶來巨大便捷，在協同作戰環境下起著至關重要的作用。

【轉】Jsduck:前端文檔產生利器Jsduck介紹及安裝使用