JSDoc은 JavaScript용 API 문서 생성기이자 TypeScript 언어 서버에서 지원하는 타입 어노테이션 형식입니다.
함수 어노테이션
/**
* Calculates total invoice sum including tax.
*
* @param {number} subtotal - Net amount before tax.
* @param {number} [taxRate=0.1] - Optional tax percentage (defaults to 10%).
* @param {string} [currency='USD'] - Three-letter ISO currency code.
* @returns {number} The calculated total invoice price.
* @throws {RangeError} When subtotal is negative.
*/
function calculateTotal(subtotal, taxRate = 0.1, currency = 'USD') {
if (subtotal < 0) throw new RangeError('Subtotal must be positive');
return subtotal * (1 + taxRate);
}
타입 선언 및 별칭 (@typedef)
/**
* @typedef {Object} UserProfile
* @property {number} id - Unique numeric identifier.
* @property {string} username - User account handle.
* @property {string} [email] - Optional contact email address.
* @property {'admin' | 'editor' | 'member'} role - Access control role.
*/
/**
* Loads user record from database.
* @param {number} id
* @returns {Promise<UserProfile>}
*/
async function getUser(id) {
// ...
}
주요 JSDoc 태그
| 태그 | 설명 | 예제 |
|---|---|---|
@type {Type} |
변수의 타입을 선언 | /** @type {string[]} */ |
@param {Type} name |
함수 매개변수를 문서화 | /** @param {HTMLElement} el */ |
@returns {Type} |
반환 값을 문서화 | /** @returns {Promise<void>} */ |
@async |
비동기 함수임을 표시 | /** @async */ |
@deprecated |
더 이상 사용되지 않음을 표시 | /** @deprecated Use fetchUser() instead */ |
@see |
외부 문서 링크 추가 | /** @see {@link https://example.com} */ |
@template T |
제네릭 타입 매개변수 선언 | /** @template T @param {T} item */ |