JSDoc.md

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`

• JsDoc 공식 문서