웹개발/javascript

[자바스크립트] JSDoc 가이드

joamashi 2025. 4. 12. 00:10
반응형

좋아요! 아래는 JSDoc의 기본 가이드와 다양한 예시를 함께 정리한 내용입니다.
JSDoc은 JavaScript 코드에 타입과 설명을 추가하여 문서화 및 코드 자동 완성을 도와주는 주석 기반 도구입니다. TypeScript를 쓰지 않아도 정적 분석과 IDE 지원을 받을 수 있습니다.

🧾 JSDoc 기본 문법

JSDoc은 /** ... */ 블록 주석 안에 @태그 형식으로 작성합니다.

/**
 * 설명 부분
 * @tag 설명
 */

📌 주요 JSDoc 태그와 예시

1. @param: 함수의 매개변수 설명

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

2. @returns 또는 @return: 반환값 설명

/**
 * 현재 시간을 ISO 문자열로 반환합니다.
 * @returns {string} ISO 포맷의 현재 시간
 */
function getCurrentTime() {
  return new Date().toISOString();
}

3. @typedef + @property: 커스텀 타입 정의

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

/**
 * 사용자 정보를 반환합니다.
 * @returns {User} 사용자 객체
 */
function getUser() {
  return { name: "Jaei", age: 28 };
}

4. @type: 변수 또는 상수의 타입 지정

/** @type {number} */
const PI = 3.14;

/** @type {Array<string>} */
const fruits = ["apple", "banana"];

5. @callback: 콜백 함수 타입 정의

/**
 * @callback SuccessCallback
 * @param {string} message - 성공 메시지
 * @returns {void}
 */

/**
 * 비동기 작업 후 콜백을 호출합니다.
 * @param {SuccessCallback} callback - 성공 시 호출되는 함수
 */
function doAsyncWork(callback) {
  setTimeout(() => {
    callback("작업 완료!");
  }, 1000);
}

6. @example: 사용 예시 추가

/**
 * 두 문자열을 연결합니다.
 * @param {string} a
 * @param {string} b
 * @returns {string}
 * @example
 * joinStrings("hi", "there"); // "hithere"
 */
function joinStrings(a, b) {
  return a + b;
}

7. @deprecated: 사용하지 말아야 할 함수 표시

/**
 * @deprecated 이 함수는 더 이상 사용되지 않습니다. 대신 newFunc을 사용하세요.
 */
function oldFunc() {
  console.log("예전 방식");
}

📦 다양한 복합 예시

/**
 * 게시글 객체 정의
 * @typedef {Object} Post
 * @property {number} id
 * @property {string} title
 * @property {string} content
 */

/**
 * 게시글 배열을 필터링합니다.
 * @param {Array<Post>} posts - 전체 게시글 목록
 * @param {string} keyword - 포함되어야 할 키워드
 * @returns {Array<Post>} 필터된 게시글 목록
 */
function filterPosts(posts, keyword) {
  return posts.filter(post => post.title.includes(keyword));
}

💡 팁

  • VSCode에서는 JSDoc 주석을 자동으로 생성하려면 /** 입력 후 Enter를 누르면 됩니다.
  • @param, @returns, @typedef는 실무에서 가장 많이 사용됩니다.
  • JSDoc만으로도 정적 타입 검사 툴인 TypeScript 수준의 도움을 받을 수 있어, 점진적인 타입 도입에 좋습니다.

🛠️ JSDoc → TypeScript 마이그레이션 가이드

✅ 기본 원칙

JSDoc으로 작성된 타입 정보를 점진적으로 .ts 또는 .tsx로 이전합니다.

마이그레이션 단계별 전략

① JSDoc만 있는 JS 파일 유지

/** @param {number} x @returns {number} */
function square(x) {
  return x * x;
}

② .ts로 확장자 변경 후 JSDoc 그대로 유지

/** @param {number} x @returns {number} */
function square(x: number): number {
  return x * x;
}

③ 타입 주석(Type Annotation)만 남기고 JSDoc 제거

function square(x: number): number {
  return x * x;
}

💡 커스텀 타입도 이렇게 변환:

/** @typedef {{ name: string, age: number }} User */

type User = {
  name: string;
  age: number;
};

⚙️ JSDoc + ESLint 설정법

🔧 목적

  • JSDoc의 누락, 오타, 순서 등을 자동으로 검사
  • 코드 퀄리티 향상

📦 설치

npm install --save-dev eslint eslint-plugin-jsdoc

📄 .eslintrc.js 또는 .eslintrc.json 설정

module.exports = {
  plugins: ["jsdoc"],
  extends: ["plugin:jsdoc/recommended"],
  rules: {
    "jsdoc/check-tag-names": 1,
    "jsdoc/check-types": 1,
    "jsdoc/require-param": 1,
    "jsdoc/require-returns": 1,
    // 추가 규칙은 필요 시 설정
  },
  settings: {
    jsdoc: {
      mode: "typescript" // JSDoc 타입 검사 강화
    }
  }
};

🔌 VS Code에서 JSDoc 자동 생성 확장 추천

💎 추천 확장 1: Document This

  • /** 입력 후 Enter만 치면 자동으로 JSDoc 생성
  • 함수, 변수, 클래스 등에 대한 주석 자동 완성
  • TypeScript 및 JSDoc 모두 지원

단축키:
Alt + Shift + D → 자동 문서 생성

💎 추천 확장 2: JSDoc Comments

  • 커스터마이징 가능 (작성 형식, 공백 포함 여부 등)
  • 사용 예시 자동 생성 옵션도 있음

💎 추천 확장 3: Auto JSDoc Comment

  • 함수 정의를 감지해 자동 주석 삽입
  • React + JS 프로젝트에서 많이 사용됨
  • 약간의 설정 커스터마이징 필요

poiemaweb.com/jsdoc-type-hint는 JSDoc을 이용한 JavaScript 타입 힌트 작성법에 대해 잘 정리된 문서

728x90
반응형