JSDoc으로 함수 주석 달기: 자주 쓰는 태그 정리

자주 쓰는 태그

태그	용도
@param	함수의 매개변수 설명
@returns (@return)	함수의 반환값 설명
@typedef	새로운 타입 정의
@property	@typedef로 정의한 객체 타입의 속성
@example	사용 예제
@deprecated	더 이상 사용하지 않는 함수·기능 표시

예시

/**
 * @typedef {Object} User
 * @property {string} name - 사용자의 이름
 * @property {number} age - 사용자의 나이
 */

/**
 * 사용자 정보를 문자열로 만든다.
 *
 * @param {User} user - 처리할 사용자 정보 객체
 * @returns {string} 처리된 사용자 정보 문자열
 *
 * @example
 * const userInfo = processUser({ name: '홍길동', age: 30 });
 * console.log(userInfo); // "이름: 홍길동, 나이: 30"
 *
 * @deprecated 향후 버전에서 제거될 예정. 대신 `newProcessUser`를 사용한다.
 */
function processUser(user) {
  return `이름: ${user.name}, 나이: ${user.age}`;
}

@typedef는 함수 주석과 분리된 별도 블록에 두는 편이 재사용하기 좋다. 에디터(VS Code 등)는 이 주석을 읽어 자동완성과 타입 힌트를 보여준다.