JSDoc

 

JSDoc

• JSDoc은 자바스크립트 코드에 주석을 추가하여 함수, 변수, 클래스 등에 대한 정보를 명확하게 기술할 수 있는 도구입니다.
• 이 주석은 /** ... */ 형식으로 작성하며, 다양한 태그를 통해 파라미터 타입, 반환값, 설명 등을 문서화할 수 있습니다.
• 자동 문서화 도구(JSDoc 툴)를 사용하여 HTML 문서로 변환할 수 있어, 프로젝트 문서를 별도로 만들 필요 없이 주석만으로도 완전한 API 문서를 생성할 수 있습니다.

 

장점

• 타입과 용도를 명확히 파악할 수 있어 코드 가독성을 높입니다.
• VSCode 등에서 타입 추론, 자동 완성, 인텔리센스 기능이 강화합니다.
• HTML 등으로 API 문서를 자동으로 생성 가능합니다.
• 다른 개발자와 협업 시 코드 가독서과 이해도를 높이고 유지보수 난이도를 낮춥니다.

 

사용방법

• JSDoc 도구를 설치하고 HTML 문서를 생성할 수 있습니다. docs 폴더에 API 문서가 자동으로 생성됩니다.

npm install -g jsdoc // JSDoc 도구 설치
jsdoc yourFile.js -d docs // API 문서 생성

 

기본적인 문법

@태그 { 타입 } 변수명 - 설명

• @태그 : JSDoc에서 의미를 정의하는 키워드 (예: @param, @returns)
• { 타입 } : 해당 요소의 데이터 타입 (예: number, string, boolean, Object, Array<string> 등)
• 변수명 : 변수 이름 또는 함수의 매개변수 이름 등
• 설명 : 변수나 반환값, 속성에 대한 간단한 설명 

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

// 변수와 객체 주석
/** @type {string} */
let username = "chatgpt";

/**
 * 사용자 정보
 * @type {{id: number, name: string}}
 */
const user = {
  id: 1,
  name: "John Doe"
};

// 클래스와 메서드
/**
 * 직사각형 클래스입니다.
 */
class Rectangle {
  /**
   * @param {number} width 너비
   * @param {number} height 높이
   */
  constructor(width, height) {
    this.width = width;
    this.height = height;
  }

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

// 예외 설정
/**
 * JSON 파싱을 시도합니다.
 * @param {string} jsonString - JSON 문자열
 * @returns {Object} 파싱된 객체
 * @throws {SyntaxError} JSON 형식 오류가 발생한 경우
 */
function parseJSON(jsonString) {
  return JSON.parse(jsonString);
}

// 사용자 객체 정의
/**
 * 주문 객체입니다.
 * @typedef {Object} Order
 * @property {number} id - 주문 번호
 * @property {User} customer - 주문자 정보
 * @property {Product[]} items - 주문한 상품 목록
 */

/**
 * 상품 정보입니다.
 * @typedef {Object} Product
 * @property {string} name - 상품명
 * @property {number} price - 가격
 */
 
 /** @type {Order} */
const order = {
  id: 1001,
  customer: {
    id: 101,
    name: "홍길동",
    isActive: true
  },
  items: [
    { name: "노트북", price: 1500000 },
    { name: "마우스", price: 25000 }
  ]
};

// 예시 문서화
/**
 * 숫자를 제곱합니다.
 * @param {number} x - 입력 숫자
 * @returns {number} 제곱 결과
 * @example
 * square(2); // 4
 * square(4); // 16
 * @example
 * square(5); // 25
 */
function square(x) {
  return x * x;
}

 

자주 사용되는 태그들

태그	설명
@param	함수 파라미터 설명
@returns or @return	반환값 설명
@type	변수의 타입 명시
@typedef	복잡한 타입을 정의할 때 사용
@property	객체 속성 정의
@example	사용 예시 추가
@deprecated	더 이상 사용되지 않는 API 표시

 

728x90

jsdoc.json

• JSDoc의 기본 동작 방식을 커스터마이징할 수 있는 설정 파일

{
  "source": {
    "include": ["src"], // 문서화할 소스 파일 또는 폴더 경로 배열
    "exclude": ["node_modules"], // 제외할 경로 목록
    "includePattern": ".+\\.js(doc)?$", // 포함할 파일의 정규식 패턴
    "excludePattern": "(^|\\/|\\\\)_" // 제외할 파일의 정규식 패턴
  },
  "opts": {
    "destination": "./docs", // 생성된 문서가 저장될 폴더
    "recurse": true, // 하위 디렉터리까지 탐색할지 여부
    "template": "node_modules/docdash", // 사용할 HTML 템플릿 경로
    "tutorials": "./tutorials", // 튜토리얼 파일 폴더 지정
  	"readme": "./README.md" // 문서 첫 페이지에 사용할 README 파일 경로
  },
  "plugins": ["plugins/markdown"], // JSDoc 기능 확장을 위한 플러그인
  "templates": {
    "cleverLinks": true, // 링크 자동 생성 여부
    "monospaceLinks": false // 링크를 모노스페이스 글꼴로 표시
  }
}