談談JSDOC對ES6的支援
阿新 • • 發佈：2019-01-06
隨著AMD與COMMONJS的深入人心，ES6與babel的組合已成為前端開發必備套件，所以也有必要更新JSDOC的寫法，為應用與技術的發展與維護提高更好的文件支援。
1. 生成文件的兩種選擇
根據前端程式碼編譯的生命週期，生成文件可以選擇在ES6編譯後或ES6編譯前，編譯後的優點是能完全相容ES3文件規範，學習成本低，所需的JSDOC註解較少，但經過測試，卻發現可信度不高，原因在於編譯後代碼與註釋的關聯性太低，甚至出現了註釋丟失的現象。
所以，本文主要討論ES6編譯前的文件生成方法。
2. 對於模組的理解
在JSDOC中，模組只是一個組合，是對類、方法、常量的一個集合，那麼問題來了，如果模組一個組合，那麼它就不能作為一個物件對待，不能擁有自身的屬性與方法。
需要特別注意的是，模組與名稱空間是兩個不同的概念，模組只是虛擬的佔位符，而名稱空間這是一個具體的物件。
3. 從模組中匯出物件的JSDOC
/**
* StiStrap module
* @module StiStrap
* @namespace StiStrap
* @desc 提供Bootstrap的Vue實現
*/
export const StiStrap = {
/**
* @see StiStrap.alert
* @static
* @public
*/
alert () {}
}對於匯出的物件，必須要新增@namespace註解，否則無法生成屬性與方法的物件關係。按上述的ES寫法，最後生成的JSDOC如下所示。
4. 更多例項
/**
* 提供Bootstrap的alert實現
* @class StiStrap.alert
* @summary 基於Vue的子元件規範實現，不可直接例項化
* @example
import { alert } from StiStrap
export defualt {
components : {
alert
}
}
*/
export default {
/**
* @lends StiStrap.alert.prototype
*/
props : {
/**
* @desc 是否顯示此元件
* @type { boolean }
*/ 5. 結論
經過實驗，在充分理解AMD與COMMONJS模組的基礎下，寫出層次豐富、結構清晰的JS文件也不是件太難的事情，更多內容請參考JSDOC官方文件。