隨著ES2015的定稿萄金，模塊化已經(jīng)成為前端開發(fā)的規(guī)范被執(zhí)行预愤，清晰的模塊化使得開發(fā)者與開發(fā)者之間的依賴便的更小钾虐，當(dāng)項目還小時，可以通過查找一下模塊源文件中的聲明就能大致了解模塊的功用吏廉。然而泞遗，隨著項目的不斷增長以及各項目之間的整合，開發(fā)者對其他模塊的內(nèi)容知之甚少席覆，如果來源于不同項目史辙，只是項目間的依賴的話，那么源代碼有可能也無法在當(dāng)前開發(fā)環(huán)境下找到佩伤，此時聊倔，開發(fā)者都會想到有個API文檔那該多好啊。
所以生巡，前端代碼文檔化勢在必行耙蔑。
前端代碼主要以js為主，主流的文檔生成器便是JSDoc孤荣，最近項目是使用的ES2105編寫的甸陌，JSDoc3.4.0之后已經(jīng)提供了對ES2015的支持。
安裝JSDoc
npm i jsdoc -g
如何使用JSDoc
同其他語言一樣盐股，文檔生成工具的原理還是通過代碼注釋去解析并根據(jù)一定的tag來生成文檔钱豁。在JSDoc文檔中明確說明了，只有以/**為開始的注釋才會被JSDoc識別疯汁，其他的注釋格式都會被忽略牲尺。
額外，JSDoc 默認(rèn)還會將項目中的README.md文件一同生成到JSDoc最后生成的文檔文件中幌蚊，或通過命令--R/-readme 指定個別文件谤碳，將其添加至所生成的文檔文件中，但文件格式必須是Markdown溢豆，此時蜒简，項目中的README.md將被忽略。
JSDoc命令行參數(shù)
JSDoc命令行幾個常用參數(shù)有以下幾個：
- -c, --configure 指定configuration file
- -d, --destination 指定輸出路徑沫换，默認(rèn)./out
- -e, --encoding 設(shè)定encoding臭蚁，默認(rèn)utf8
- -p, --private 將private注釋輸出到文檔，默認(rèn)不輸出
- -P, --package 指定package.json file
- -r, --recurse 查詢子目錄
- -t, --template 指定輸出文檔template
- -u, --tutorials 指定教程路徑讯赏，默認(rèn)無
JSDoc配置文件
同許多js工具一樣垮兑，JSDoc也有配置文件，可以通過設(shè)定配置文件來定制JSDoc漱挎。如果沒有指定configuration file系枪，將會使用一下配置。
{
"tags": {
"allowUnknownTags": true, // 允許使用自定義tag
"dictionaries": ["jsdoc","closure"] // 定義tag集
},
"source": {
"includePattern": ".+\\.js(doc)?$", // 將以.js, .jsdoc結(jié)尾的文件作為源文件
"excludePattern": "(^|\\/|\\\\)_" // 忽略以_開頭的文件夾及文件
},
"plugins": [],
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
以上這個是默認(rèn)配置磕谅，下面解釋幾個常用配置私爷。
- source：顧名思義是用來指定源文件的雾棺，在其之下包含了4個屬性，其中兩個已經(jīng)在默認(rèn)配置中出現(xiàn)過了衬浑。
|- include: [ array of paths to files to generate documentation for ], // 源文件路徑數(shù)組
|- exclude: [ array of paths to exclude ], // 排除文件路徑數(shù)組
|- includePattern: a regular expression, // 接受一個正則表達式捌浩，當(dāng)文件名匹配這個正則時，執(zhí)行JSDoc
|- excludePattern: a regular expression, // 接受一個正則表達式工秩，當(dāng)文件名匹配這個正則時尸饺，JSDoc忽略該文件
JSDoc以以下的順序執(zhí)行這些屬性：- 根據(jù)include獲取目標(biāo)文件
- 根據(jù)includePattern篩選由第一步得到的目標(biāo)文件
- 根據(jù)excludePattern篩選由第二步得到的文件
- 最后根據(jù)exclude屬性，排除由第三步得到的文件結(jié)果集助币，排除之后的文件便是JSDoc需要執(zhí)行的源文件浪听。
- tags: 用來指定tag庫，tags下面有2個屬性眉菱，分別是
|- allowUnknownTags: 用來告訴JSDoc如何處理標(biāo)簽庫以外的tag迹栓，設(shè)為false時，JSDoc不會處理標(biāo)簽庫以外的tag俭缓，但會記錄一個警告克伊，默認(rèn)為true
|- dictionaries: 數(shù)組格式，指定標(biāo)簽庫尔崔，標(biāo)簽庫越靠前答毫，優(yōu)先度越高 - opts: 命定行參數(shù)可以在此屬性下配置褥民，列如：
"opts": {
"template": "templates/default", // same as -t templates/default
"encoding": "utf8", // same as -e utf8
"destination": "./out/", // same as -d ./out/
"recurse": true, // same as -r
"tutorials": "path/to/tutorials", // same as -u path/to/tutorials
}
- plugins: 配置額外的插件季春，如markdown插件，與此同時消返，JSDoc也可以編寫自定義插件做額外的處理载弄。
- templates: 可以用來配置默認(rèn)template的格式，或另外指定自定義的template
Tags
上文說了那么多撵颊，主要說的都是JSDoc如何使用和配置宇攻，和平時的編碼過程中注釋怎么寫，要使用哪些標(biāo)簽并沒什么聯(lián)系倡勇，現(xiàn)在就來講講最重要的Tag逞刷。
JSDoc中將tag分為兩類，Block tag和Inline tag妻熊。
- Block tag: 在JSDoc中是最高級別的注釋夸浅，通常用來提供代碼的詳細信息。它以
@開頭扔役，除了位于注釋最后的Block tag帆喇，其他Block tag必須緊跟換行符 - Inline tag: 通常是
Block tag的文字內(nèi)容或描述，它用一對{}包裹亿胸。
Block tag也就是我們平時最常用的注釋標(biāo)簽坯钦，在此列舉一些常用的tag
- @abstact: 抽象
- @access: 也可以直接使用@private, @protect, @public來替代
- @alias: 別名
- @augments | @extends: 繼承
- @author: 作者
- @borrows: 引用预皇，用來引用文檔中的另一個記錄
- @callback: 回調(diào)
- @class | @constructor: 類，ES2015規(guī)范下不用顯示添加該tag婉刀，JSDoc會默認(rèn)將注釋第一段轉(zhuǎn)換為@class
- @classdesc: 類描述
- @const | @constant: 常量吟温，ES2015規(guī)范下使用const定義變量，不用顯示添加該tag
- @copyright: 版權(quán)
- @default | @defaultvalue: 默認(rèn)值突颊，JSDoc會自動識別簡單類型的值：string, number, boolean and null.
- @deprecated: 廢棄
- @desc | @description: 描述
-
@emits | @fires: 發(fā)出溯街，函數(shù)內(nèi)部會觸發(fā)自定義事件，即包含
@eventtag - @enum: 枚舉
-
@event: 事件洋丐，自定義事件觸發(fā)處呈昔，父方法應(yīng)添加
@firestag - @example: 舉例
- @exports: 導(dǎo)出，ES2015規(guī)范下使用exports不用顯示添加該tag
- @external | @host: 外部引用
- @file | @fileoverview | @overview: 文件
- @func | @function | @method: 方法
- @global: 全局變量
- @license: 許可證
- @member | @var: 成員變量
- @mixin: 混合
- @module: 模型
-
@name: 名稱友绝，用于抽象方法或匿名函數(shù)堤尾，變更現(xiàn)有方法的方法名使用
@aliastag - @namespace: 命名空間
- @override: 重寫
- @param | @arg | @argument: 參數(shù)
-
@property | @prop: 屬性，多用于靜態(tài)對象迁客，區(qū)別于
@enum標(biāo)簽郭宝，property標(biāo)簽可以設(shè)定不用類型，而@enum標(biāo)簽是同一類型的值的集合 - @readonly: 只讀
- @requires: 依賴
- @return | @returns: 返回
- @see: 參閱掷漱，ref
- @since: 添加版本
- @summary: 總結(jié)
- @this: 聲明方法中的this指代
- @throws | @exception: 異常
- @type: 類型
Inline tag
- {@link} 生成一個鏈接指向定義的
namepath或者URL
Namepaths
namepath在JSDoc中起著至關(guān)重要的作用粘室，JSDoc namepath會提供一個唯一的標(biāo)識給任意一個變量，這使得你在使用inline tag時卜范，可以方便的找到任何一個變量衔统，從而提供一個指向該變量的鏈接。
MyConstructor // 父元素
MyConstructor#instanceMember // 成員變量使用#
MyConstructor.staticMember // 靜態(tài)變量使用.
MyConstructor~innerMember // 內(nèi)部成員使用~
// module使用:
