JSDoc 複雜 Object 的標註方式

Redux state 的結構設計，通常會是龐大又複雜的巢狀 object，要如何使用 JSDoc 來進行 object 結構的標註呢 ?

使用 @typedef 標籤可以定義一個 type，詳述每個 property 的資料結構，特別是當我們希望將多個 object property 的 type 統整為單一個的 type 會很好用（也就是巢狀 object 的情況）

首先先從比較簡單的情境開始示範

我們使用 @typedef 定義 Person 的 type，並在實際宣告 object 的時候，使用 @type {Person} 來標記 person 要使用這個 type

/**
 * @typedef {Object} Person
 * @property {string} name - 名字
 * @property {number} age - 年齡
 */

/**
 * @type {Person}
 */

const person = {
  name: "John",
  age: 30,
};

我們可以將 Person 變得更為複雜，組成巢狀的結構，具體做法如下 :

Person 有一個 property Address ，且為 object
Address 使用 @typedef 來定義 type，這樣可以使整體標註文件更加分離，避免使得 @typedef {Object} Person 變成一長串

/**
 * @typedef {Object} Address
 * @property {string} street - 街道
 * @property {string} city - 城市
 * @property {string} zip - 郵遞區號
 */

/**
 * @typedef {Object} Person
 * @property {string} name - 名字
 * @property {number} age - 年齡
 * @property {Address} address - 地址
 */

/**
 * @type {Person}
 */
const person = {
  name: "John",
  age: 30,
  address: {
    street: "123 Main St",
    city: "New York",
    zip: "10001",
  },
};

如果使用 Visual Studio Code，按著 Crtl (Cmd) 用滑鼠左鍵點擊 * @property {Address} address - 地址 之中的 Iddress，畫面會自動跳轉到 Address 的 type 定義區塊，==透過這樣的方式可以方便地瀏覽每個 type==

JSDoc 實現 Enum

避開魔法字串 - constant 和 enum object 使用時機

若要使用純 JavaScript 來實現 enum 的效果，我們需要定義兩種型別 : Gender 和 GenderEnum

Gender type 定義時，就列出所有的字串實際值
GenderEnum 則引用 Gender type 來表達所有的 property 實際值不會脫離 Gender 的範疇，作為 enum object 引用的 type
Person ，也引用 Gender Type 表達 gender 的值都會落入這些範疇

/** @typedef {'male'|'female'|'non-binary'|'prefer not to say'} Gender */

/**
 * @typedef GenderEnum
 * @property {Gender} MALE
 * @property {Gender} FEMALE
 * @property {Gender} NON_BINARY
 * @property {Gender} PREFER_NOT_TO_SAY
 * Gender 的型別標註可提醒開發者 : 如果加入新的 property, Gender 型別本身也要進行更新
 */

/** @type {GenderEnum} */
export const GENDER = {
  MALE: "male",
  FEMALE: "female",
  NON_BINARY: "non-binary",
  PREFER_NOT_TO_SAY: "prefer not to say",
};

/**
 * @typedef {Object} Address
 * @property {string} street - 街道
 * @property {string} city - 城市
 * @property {string} zip - 郵遞區號
 */

/**
 * @typedef {Object} Person
 * @property {string} name - 名字
 * @property {number} age - 年齡
 * @property {Address} address - 地址
 * @property {Gender} gender 性別
 */

/**
 * @type {Person}
 */
const person = {
  name: "John",
  age: 30,
  address: {
    street: "123 Main St",
    city: "New York",
    zip: "10001",
  },
  gender: GENDER.MALE,
};

實際使用中，我們可以使用 GENDER.MALE 來取代實際輸入 'male'，除了有更好的自動提示，也可以避免字串輸入錯誤的風險

todo: 協作快速上手

JSDoc 實現 Enum​

JSDoc 實現 Enum