JSDoc

JSDoc?

• JSDoc은 JavaScript 코드에 주석을 추가하여 코드의 구조와 기능을 문서화하는 도구입니다.
• JSDoc 주석은 코드의 가독성을 높이고, 자동으로 API 문서를 생성하는 데 유용합니다.
• JSDoc 주석은 일반적으로 /** ... */ 형식으로 작성됩니다.

 

JSDoc 태그

• @param: 함수의 매개변수를 설명합니다.
• @returns: 함수의 반환 값을 설명합니다.
• @typedef: 사용자 정의 타입을 정의합니다.
• @property: 객체의 속성을 설명합니다.
• @class: 클래스를 설명합니다.
• @method: 클래스의 메서드를 설명합니다.

 

사용 예시

1. 함수 주석:

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

3. 객체 주석:

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

/**
 * 사용자 정보를 출력합니다.
 * @param {User} user - 사용자 객체.
 */
function printUser(user) {
    console.log(`Name: ${user.name}, Age: ${user.age}`);
}

5. 클래스 주석:

/**
 * 자동차 클래스.
 */
class Car {
    /**
     * 자동차 생성자.
     * @param {string} make - 제조사.
     * @param {string} model - 모델.
     */
    constructor(make, model) {
        this.make = make;
        this.model = model;
    }

    /**
     * 자동차 정보를 반환합니다.
     * @returns {string} 자동차 정보.
     */
    getInfo() {
        return `${this.make} ${this.model}`;
    }
}

JSDoc을 사용하면 코드의 이해도를 높이고, 팀원 간의 협업을 원활하게 할 수 있습니다.
JSDoc을 통해 생성된 문서는 API 문서화 도구를 사용하여 HTML 형식으로 변환할 수 있습니다.

---

TypeScript에서 JSDoc 사용

• JSDoc은 TypeScript(TS)에서도 사용할 수 있지만, TypeScript 자체가 강력한 타입 시스템을 제공하기 때문에 JSDoc의 필요성이 줄어들 수 있습니다.
• TypeScript는 타입을 명시적으로 정의할 수 있는 기능을 제공하므로, JSDoc 주석 없이도 코드의 타입을 명확하게 표현할 수 있습니다.
• 그러나 TypeScript 코드에 JSDoc을 사용하는 것은 여전히 유용할 수 있습니다. 특히 다음과 같은 경우에 도움이 됩니다:

1. 문서화: JSDoc을 사용하여 함수, 클래스, 인터페이스 등의 설명을 추가하면 코드의 가독성을 높이고, 다른 개발자들이 이해하기 쉽게 만들 수 있습니다.
2. 타입 정보 보강: TypeScript의 타입 시스템을 보완하기 위해 JSDoc을 사용할 수 있습니다. 예를 들어, 복잡한 타입이나 제네릭 타입을 설명할 때 유용합니다.
3. IDE 지원: 많은 IDE(예: Visual Studio Code)는 JSDoc 주석을 인식하여 코드 완성 및 타입 정보를 제공하므로, JSDoc을 사용하면 개발 경험이 향상될 수 있습니다.

 

사용 예시

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

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

/**
 * 사용자 정보를 출력합니다.
 * @param {User} user - 사용자 객체.
 */
function printUser(user: { name: string; age: number }): void {
    console.log(`Name: ${user.name}, Age: ${user.age}`);
}