學習紀錄 | JSDoc 是什麼？怎麼寫？

Mohammad Rahmani on Unsplash

什麼是 JSDoc

JSDoc 全名是 JavaScript Documentation，顧名思義是為 JavaScript 所使用的 API 文件，在程式碼內透過註解的方式撰寫，運行後 JSDoc 會自動掃描註解內容，並生成一份網頁版的文件，對於沒有使用 Typescript 開發的專案，也能達成型別檢查的用途，非常方便好用！

寫 JSDoc 的第一步

JSDoc 註解的方式會以/** 開頭， */ 結尾，中間使用不同的 @tag 來定義函式、描述詞、傳入參數、回傳值...等內容，每個函式都需要各自寫成一塊，不能全部寫在同個註解內哦～

註解會寫在變數或函式的上方，直接看一個範例吧，先了解一下大致的撰寫方式，等等再詳細介紹常用的 @tag 有哪些，範例：

/**
 * @function add
 * @description add two number
 * @param {Number} num1 - 後面可以加上對 num1 的描述
 * @param {Number} num2
 * @returns {Number}
*/
function add(num1, num2) {
  return num1 + num2
}

滑鼠移動到 add() 的時候，就能看到相關的註解內容囉！

文件生成

註解撰寫完成後，總要看到成果吧，於是我們可以先來簡單生成文件，看看文件長什麼樣

• 在專案內安裝 JSDoc 套件 npm install jsdoc
• 使用指令jsdoc + 文件路徑，即可編譯並自動產生一個名為 out 的文件夾
• • 可自行新增 jsdoc.config.json 檔案來修改文件生成的設定
  • 也可在 package.json 的 script 中，加入生成文件的指令 "doc": "jsdoc -c jsdoc.config.json"

從 out 文件夾內開啟剛剛那份檔案，就可以看到文件內有 add function 啦！如果不喜歡原生文件的樣式，也可以使用其他套件（如：clean-jsdoc-theme）來客製化你的JSDoc哦～

接下來再熟悉一些常用的@tag ，掌握 JSDoc 就不難啦～剛開始學 JavaScript 時，都會先宣告常數與變數，以及學習不同類型的型別，再來學 function 對吧，以下會按照同樣的方式來介紹常用的@tag

定義常數&型別

• @constant / @const 用來定義常數，與使用 const 定義常數的概念相同，定義後的值不可被修改
• @type {Type} 用來定義型別，變數不需要使用額外標籤，直接定義型別即可，{} 內可以是基本型別或其他客製化組合的類型(@typedef 後面會介紹)

/**
 * @const name
 * @type {String}
 */
const name = 'Amber'

/**
 * @description favorite color
 * @type {String} color
 */
 let color = 'yellow'

• @const 可與 @type 合併撰寫

/**
 * @const {String} name
 */
const name = 'Amber'​

• @property 定義物件屬性，如果屬性是可選的，放在括號中 ex @property {String} [favoriteColor]

/**
	 * @type {Object} person
	 * @property {String} name
	 * @property {String} [favoriteColor]
	 */
 const person = {
	 name: 'Amber',
	 favoriteColor: 'yellow'
 }

定義函式

@function 定義函式
@description 函式的描述內容
@param 函式的參數
@returns 函式返回值
@example 寫一些函式 input/output 範例參考

/**
* @typedef {Object} myObject
* @property {String} name
* @property {Number} age
* @property {Boolean} isDeveloper
*/

/**
 * @function createPerson
 * @description Create a person object
 * @param {String} name - The name of the person
 * @param {Number} age - The age of the person
 * @param {Boolean} isDeveloper - The developer status of the person
 * @returns {myObject} - The person object
*/
function createPerson(name, age, isDeveloper) {
  return {
    name:name,
    age,
    isDeveloper
  }
}

定義客製化的型別

@typedef {Type} 定義客製化型別

有仔細看的讀者應該會發現，上面 createPerson函式的 return 值是一個物件，但是我給他定義的型別是 myObject 吧，這就是客製化型別 @typedef 的用途！如果有巢狀物件需要定義時，可以使用 @typedef 先定義客製化物件內容，再用 @type 來定義物件型別，將型別指定為 typedef 所定義的內容，再來看一個範例吧：

/**
* @typedef {Object} Class
* @property {String} classTitle
* @property {String} teacher
* @property {Number} classroom
*/

/**
* @type {Array<Class>} myClass
*/

const myClass = [
	{
		classTitle: 'math',
		teacher 'mathTeacher',
		classroom: 102
	},
	{
		classTitle: 'art',
		teacher 'artTeacher',
		classroom: 105
	}
]​

其他常用 tag

@module 將當前文件定義為模組，文件內所有參照都屬於這個 module
@global 跨檔案使用@typedef，將會忽略程式碼本身作用域，定義為全域皆可使用 @throws 定義 function 會拋出的錯誤
@see 表示可以參考另一個文件內容或外部資源，外部資源用 @link 連結
@class /@constructor 將內容定義為 Class，通常會自動識別，不需要特別撰寫定義

那 JSDoc 介紹差不多就到這邊啦，我是Amber，前端學習中，歡迎交流討論～🧸

參考資料

沒辦法用 TypeScript？別擔心，你還可以寫 JSDoc 標注類型
前端使用 JSDoc 生成文件

Step-by-Step Guide to JSDoc and TypeScript in Modern JavaScript Projects in 15 Minutes!