[JavaScript] JSDoc이란?

JSDoc

---

 

목차

 

JSDoc이란?

사용하는 이유

 

 

---

 

---

[JSDoc이란?]

코드 리뷰를 받으면서 JSDoc을 알게 되었다.

JSDoc은 자바스크립트에서 소스 코드와 함께 문서 주석을 직접 추가할 수 있는 방식이다.

<예시 코드>

/**
 * 두 숫자를 더합니다.
 *
 * @param {number} a 첫 번째 숫자
 * @param {number} b 두 번째 숫자
 * @returns {number} 합계
 *
 * @example
 * const result = add(2, 3);
 * console.log(result); // 5
 */
export function add(a: number, b: number): number {
    return a + b;
}

 

자바스크립트에서 라이브러리의 API를 문서화하기 위해 사용한다.

JSDoc을 사용하여 모듈, 네임스페이스, 클래스, 메서드, 매개변수 등 다양한 코드를 체계적으로 문서화할 수 있다.

JSDoc 주석은 문서화할 코드 바로 앞에 있어야 한다.

각 주석은 /** 로 시작해야 JSDoc 파서가 인식할 수 있다.

반대로 /*,/***, 또는 별 3개 이상으로 시작하는 주석은 무시된다.

또 필요에 따라 주석 블록의 구문 분석을 억제할 수 있다.

 

 

---

[사용하는 이유]

다음과 같은 코드가 있다.

export type User = {
    id: number;
    name: string;
    email?: string;
};

export type UserCardProps = {
    user: User;
    onClick?: (user: User) => void;
};

export default function UserCard({ user, onClick }: UserCardProps): JSX.Element {
    return (
        <div
            className="user-card"
            onClick={() => onClick?.(user)}
            style={{
                border: "1px solid #ccc",
                borderRadius: "8px",
                padding: "12px",
                cursor: onClick ? "pointer" : "default",
            }}
        >
            <h2>{user.name}</h2>
            <p>ID: {user.id}</p>
            {user.email && <p>Email: {user.email}</p>}
        </div>
    );
}

 

이 코드를 다른 컴포넌트에서 사용한다면 다음과 같이 나타난다.

Board에서 UserCard 컴포넌트를 사용할 때

Board에서 UserCard 컴포넌트를 사용할 때

 

이 UserCard 컴포넌트가 정확히 어떤 코드인지, 어떻게 사용해야 하는지 개발자는 알 수 없다.

만약 JSDoc을 사용한다면 다음과 같이 사용할 수 있다.

/**
 * 사용자 정보 타입
 */
export type User = {
    /** 사용자 ID */
    id: number;
    /** 사용자 이름 */
    name: string;
    /** 이메일 주소 (선택) */
    email?: string;
};

/**
 * UserCard 컴포넌트 Props
 */
export type UserCardProps = {
    /** 사용자 객체 */
    user: User;
    /** 카드 클릭 핸들러 (선택) */
    onClick?: (user: User) => void;
};

/**
 * 사용자 카드 컴포넌트
 *
 * @param {UserCardProps} props - 컴포넌트 props
 * @returns {JSX.Element} 렌더된 사용자 카드
 *
 * @example
 * <UserCard user={{ id: 1, name: "홍길동", email: "hong@test.com" }} />
 */
export default function UserCard({ user, onClick }: UserCardProps): JSX.Element {
    return (
        <div
            className="user-card"
            onClick={() => onClick?.(user)}
            style={{
                border: "1px solid #ccc",
                borderRadius: "8px",
                padding: "12px",
                cursor: onClick ? "pointer" : "default",
            }}
        >
            <h2>{user.name}</h2>
            <p>ID: {user.id}</p>
            {user.email && <p>Email: {user.email}</p>}
        </div>
    );
}

 

코드를 사용할 때 다음과 같이 나타난다.

어떤 props를 사용해야 하는지 props는 어떻게 구성되어야 하는지를 알 수 있다.

JSDoc을 사용한 경우

 

이렇게 코드를 작성할 수 있다.

import UserCard from "./components/UserCard";

function Board() {
    const user = {
        id: 11,
        name: "김익명",
        email: "unknow@test.com",
    };

    return <UserCard user={user} />;
}

export default Board;

// 또는

import UserCard, { User } from "./components/UserCard";

function Board({ user }: { user: User }) {
    return <UserCard user={user} />;
}

export default Board;

 

• 타입과 구조 명확화 : props, 함수 파라미터, 반환값 등을 문서화하여 사용 방법을 쉽게 이해할 ㅅ 있다.
• 자동 완성 지원 : IDE에서 JSDoc 주석 기반 자동 완성 기능을 활용할 수 있다.
• 협업 효율 향상 : 다른 개발자가 코드를 빠르게 이해하고 사용할 수 있다.

 

주요 태그 예시

• @param {타입} 이름 설명 → 함수 매개변수 설명
• @returns {타입} 설명 → 반환값 설명
• @example → 사용 예시 제공
• @typedef → 사용자 정의 타입 정의

 

<정리>

이렇게 작성하면 IDE에서 자동완성, 타입추론 같은 지원을 받을 수 있다.

• 주석 기반: /** ... */ 블록 주석을 사용.
• 타입 명시 가능: JavaScript는 동적 타입 언어지만, JSDoc으로 변수, 매개변수, 반환값의 타입을 지정할 수 있음.
• IDE 지원: VS Code 같은 에디터에서 JSDoc을 쓰면 자동 완성, 타입 힌트, 코드 탐색이 훨씬 좋아짐.
• 문서 생성기: jsdoc CLI 같은 도구로 실제 API 문서를 HTML 등으로 뽑아낼 수도 있음.

 

 

 

 

---

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!😊

댓글과 좋아요는 큰 힘이 됩니다!

 

[ 참고자료 ]

 

https://jsdoc.app/

Use JSDoc: Index

 

https://poiemaweb.com/jsdoc-type-hint

JSDoc을 사용하여 자바스크립트에 타입 힌트 제공하기 | PoiemaWeb

 

https://www.typescriptlang.org/ko/docs/handbook/jsdoc-supported-types.html

Documentation - JSDoc Reference