본문으로 건너뛰기

JsDoc

Summary​

JsDoc은 JavaScript 코드에 주석을 추가하여 함수, 변수, 클래스 등의 정보를 명확하게 문서화하는 도구이다. 주석 기반으로 작성되며, 코드 가독성을 높이고 IDE에서 자동완성 및 타입 힌트를 제공하는 데 도움을 준다.

Details​

JsDoc 태그 리스트​

JsDoc에서 자주 사용되는 태그와 그 기능은 다음과 같다.

태그설명
@param함수의 매개변수 설명
@returns함수의 반환값 설명
@type변수의 타입 지정
@typedef사용자 정의 타입 선언
@property객체 속성의 타입 지정
@example코드 예제 제공
@deprecated더 이상 사용되지 않는 API 표시
@see참조할 관련 정보 추가
@throws함수에서 발생할 수 있는 예외 설명
@async비동기 함수 표시
@callback콜백 함수 타입 정의
@private내부적으로만 사용되는 항목 지정
@public공개 API로 사용됨을 명시
@readonly읽기 전용 속성 정의

JsDoc 사용 예시​

/**
 * 두 개의 숫자를 더하는 함수입니다.
 *
 * @param {number} a - 첫 번째 숫자
 * @param {number} b - 두 번째 숫자
 * @returns {number} 두 숫자의 합
 */
function add(a, b) {
  return a + b;
}

/**
 * 사용자 목록을 반환하는 함수입니다.
 *
 * @returns {User[]} 사용자 객체 배열
 */
function getUsers() {
  return [
    {id: 1, name: 'Alice', isActive: true},
    {id: 2, name: 'Bob', isActive: false},
  ];
}

위 예시에서:

  • add 함수는 @param 태그를 사용하여 매개변수 a와 b의 타입과 설명을 제공하고, @returns 태그로 반환값의 타입과 설명을 명시한다.
  • getUsers 함수는 @returns 태그를 통해 User 객체의 배열을 반환함을 나타낸다.

이러한 주석을 통해 코드의 가독성과 유지보수성이 향상되며, IDE의 자동완성 및 타입 힌트 기능을 활용할 수 있다.

JsDoc의 장점​

JsDoc을 사용함으로써 다음과 같은 이점을 얻을 수 있다.

  1. 가독성 향상
    • 함수와 변수의 용도를 명확하게 설명할 수 있어 코드 이해도를 높인다.
  2. IDE 지원
    • VSCode, WebStorm과 같은 IDE에서 자동완성 및 타입 힌트 기능을 제공받을 수 있다.
  3. 자동 문서화 가능
    • jsdoc CLI 도구를 사용하면 HTML 형식의 API 문서를 자동으로 생성할 수 있다.
  4. 타입 검증 효과
    • TypeScript 없이도 타입 힌트를 제공하여 코드의 안정성을 높일 수 있다.
  5. 협업 효율성 증가
    • 여러 개발자가 동일한 프로젝트에서 협업할 때 함수와 객체의 역할을 쉽게 공유할 수 있다.

JsDoc의 단점​

하지만 JsDoc에도 몇 가지 한계가 있다.

  1. TypeScript 대비 제한적 타입 지원
    • JsDoc만으로는 복잡한 타입(예: 제네릭, 유틸리티 타입 등)을 완벽하게 표현하기 어렵다.
  2. 주석 유지보수 필요
    • 코드가 변경될 때 주석도 함께 관리해야 하므로 유지보수 부담이 증가할 수 있다.
  3. 런타임 타입 검사가 없음
    • JsDoc은 정적 분석을 도울 뿐, 실행 시점에서 타입 검사를 수행하지 않는다.
  4. 초기 학습 필요
    • 다양한 태그와 문법을 익히는 과정이 필요하며, 적절한 활용을 위해 학습 시간이 필요하다.

Reference​

link: External reference`