JSDoc

• JSDoc은 JavaScript 코드에 주석을 추가하여 코드의 문서화를 돕는 마크업 언어이다.
• 이를 통해 함수, 클래스, 메서드, 변수 등에 대한 설명을 제공하고, 코드의 사용 방법을 명확하게 설명할 수 있다.
• /** 로 시작하는 주석의 형태를 띄고 있다.

---

사용방법

1 . 함수 주석

/**
 * 두 숫자의 합을 반환합니다.
 *
 * @param {number} a 첫 번째 숫자.
 * @param {number} b 두 번째 숫자.
 * @returns {number} 두 숫자의 합.
 */
function add(a, b) {
  return a + b;
}

2. 객체 주석

/**
 * 사용자 정보를 나타내는 객체.
 * @typedef {Object} User
 * @property {string} name - 사용자의 이름.
 * @property {number} age - 사용자의 나이.
 * @property {boolean} isAdmin - 관리자 여부.
 */

/** @type {User} */
const user = {
  name: "John Doe",
  age: 30,
  isAdmin: true,
};


/**
 * 2번째 방법
 * @param {object} config
 * @param {boolean} config.debug
 * @param {string} config.url
 * @returns {boolean}
 */
export function init(config) {
  return true;
}

3. 클래스 주석

/**
 * 직사각형을 나타내는 클래스.
 */
class Rectangle {
  /**
   * 직사각형 인스턴스를 생성합니다.
   * @param {number} width - 직사각형의 너비.
   * @param {number} height - 직사각형의 높이.
   */
  constructor(width, height) {
    /** @type {number} */
    this.width = width;
    /** @type {number} */
    this.height = height;
  }

  /**
   * 직사각형의 면적을 계산합니다.
   * @returns {number} 직사각형의 면적.
   */
  getArea() {
    return this.width * this.height;
  }
}

4. 주요 JSDoc 태그

• @param {type} name description - 함수 매개변수를 설명.
• @returns {type} description - 함수의 반환값을 설명.
• @type {type} - 변수나 속성의 타입을 설명.
• @typedef {type} name - 사용자 정의 타입을 설명.
• @property {type} name description - 객체 속성을 설명.
• @class - 클래스를 설명.
• @constructor - 생성자를 설명.
• @extends {type} - 상속을 설명.
• @implements {type} - 인터페이스 구현을 설명.
• @throws {type} description - 함수가 던질 수 있는 예외를 설명.
• @example - 예제 코드를 제공.

---

TypeScript와 같이 사용하기

• @ts-check 태그를 통해서 JavaScript 파일을 TypeScript가 체크하도록 할 수 있다.
• JSDoc의 태그를 사용하면 JavaScript의 코드 변경 없이 주석의 추가를 통해서 TypeScript와 같이 사용 할 수 있다

예제

1. 이러한 JavaScript함수를 TypeScript 환경에서 쓰고자 한다면

2. 타입 스크립트는 해당 함수의 타입을 모르기 때문에 추론하려고 한다.(에러발생 가능성)

3.하지만 JSDoc을 이용하여 매개변수와 리턴값의 타입을 명시하면

4. TypeScript는 해당 함수의 매개변수,리턴타입을 명확히 알 수 있게 된다.