學習紀錄 | JSDoc 是什麼？怎麼寫？
什麼是 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 提示
文件生成
註解撰寫完成後，總要看到成果吧，於是我們可以先來簡單生成文件，看看文件長什麼樣
- 在專案內安裝 JSDoc 套件
npm install jsdoc - 使用指令
jsdoc + 文件路徑，即可編譯並自動產生一個名為 out 的文件夾 - 可自行新增
jsdoc.config.json檔案來修改文件生成的設定 - 也可在
package.json的 script 中，加入生成文件的指令"doc": "jsdoc -c jsdoc.config.json"
- 可自行新增
out 資料夾
從 out 文件夾內開啟剛剛那份檔案，就可以看到文件內有 add function 啦！如果不喜歡原生文件的樣式，也可以使用其他套件（如：clean-jsdoc-theme）來客製化你的JSDoc哦～
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!
