Jsdoc, ts, Typedoc

1단계: JSDoc 기본 이해

1. JSDoc이란 무엇인가?

• 정의:
  JSDoc은 JavaScript/TypeScript 코드에 주석 형태로 문서를 작성할 수 있게 해주는 표준 주석 문법입니다.
• 주요 목적:
  • 코드 설명 추가 (함수/변수/클래스/모듈 등)
  • IDE 자동 완성 및 타입 힌트 제공
  • 문서 생성 도구 (ex. TypeDoc, JSDoc)에서 HTML API 문서 생성
  • 유지보수와 협업에서 커뮤니케이션 비용 절감

---

2. JSDoc 블록 주석 구조

• 형식:
  주석은 항상 /** */로 감싸며, 각 줄 앞에 *를 붙입니다.

/**
 * 사용자 정보를 가져옵니다.
 * @param userId - 사용자 ID
 * @returns 사용자 이름
 */
function getUserName(userId: string): string {
  return `User-${userId}`;
}

• 포인트
  • /**로 시작하고 */로 끝납니다
  • * 기호는 줄마다 앞에 붙이지만 필수는 아님 (가독성 차원에서 권장)
  • @tag 형식의 태그를 통해 의미와 구조를 지정

---

3. JS/TS에서 JSDoc의 역할

JavaScript에서는:

• 타입이 없기 때문에 @param, @returns, @type 등으로 타입 지정까지 해야 함

TypeScript에서는:

• 타입은 TS가 담당하므로 @param, @returns는 설명용으로만 사용
• 그러나 @example, @deprecated, @see, @remarks 같은 문서 중심 태그는 그대로 유용

---

실습 1: 간단한 함수에 JSDoc 작성

/**
 * 숫자를 제곱합니다.
 * @param n 제곱할 숫자
 * @returns 결과 숫자
 */
function square(n: number): number {
  return n * n;
}

실습 2: VSCode에서 커서를 함수에 올려보고 JSDoc 툴팁 확인

---

주요 JSDoc 태그

---

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

• 역할: 인자의 이름, 타입, 설명을 문서화합니다.
• JS에서는 타입까지 지정, TS에서는 설명만 사용하는 경우가 많습니다.

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

TS에서는 이렇게 간단히 쓸 수 있습니다:

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

---

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

• 역할: 함수의 반환값이 무엇인지 설명합니다.
• @returns {타입} 설명 형식

/**
 * 현재 시간을 문자열로 반환합니다.
 * @returns 현재 시간 (HH:mm:ss)
 */
function getCurrentTime(): string {
  return new Date().toLocaleTimeString();
}

---

3. @typedef, @type: 커스텀 타입 선언

• JS 전용: TypeScript에서는 사용하지 않고 type이나 interface로 대체
• JS 코드에서 타입 정의와 함께 자동 완성 유도 가능

/**
 * @typedef {Object} User
 * @property {string} name
 * @property {number} age
 */

/**
 * @type {User}
 */
const user = {
  name: 'Heeseong',
  age: 30,
};

TypeScript 환경에서는 이 대신 아래처럼 타입 선언을 사용하는 것이 일반적입니다:

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

---

4. @example: 사용 예시 추가

• 역할: 함수나 클래스의 사용법을 코드 블록 형태로 설명
• 문서화/협업에서 매우 중요 — 실제 사용 시나리오 제공

/**
 * 이름으로 인사말을 만듭니다.
 * @param name 사용자 이름
 * @returns 인사 문자열
 * @example
 * greet('Heeseong');
 * // → 'Hello, Heeseong!'
 */
function greet(name: string): string {
  return `Hello, ${name}!`;
}

---

 

@param	함수 매개변수 설명	둘 다 사용
@returns	반환값 설명	둘 다 사용
@typedef	JS에서 커스텀 타입 정의	JS 전용
@type	특정 변수/상수에 타입 부여	JS 전용
@example	함수 사용 예시 제공	둘 다 사용

---

2단계: 복잡한 타입과 구조 표현

---

1. 객체 타입 주석 (@param, @returns)

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

• JS에서는 객체 구조를 주석으로 직접 작성
• TS에서는 타입 정의된 구조체를 주로 사용

---

2. 배열 타입 표현

/**
 * 점수 목록의 평균을 구합니다.
 * @param {number[]} scores 점수 배열
 * @returns {number} 평균값
 */
function average(scores: number[]): number {
  return scores.reduce((a, b) => a + b, 0) / scores.length;
}

• string[], Array<number> 모두 가능
• {Array<string>} 같은 구문도 허용됨

---

3. 커스텀 타입 정의 (@typedef)

/**
 * @typedef {Object} Product
 * @property {string} name 상품명
 * @property {number} price 가격
 * @property {boolean} inStock 재고 여부
 */

/**
 * 상품 정보를 출력합니다.
 * @param {Product} product 상품 객체
 */
function display(product: { name: string; price: number; inStock: boolean }) {
  console.log(product.name, product.price, product.inStock);
}

• JS 전용 커스텀 타입 정의 방법
• TS에서는 type이나 interface 사용

---

4. 제네릭 표현 (@template)

/**
 * 배열의 첫 번째 요소를 반환합니다.
 * @template T
 * @param {T[]} arr 입력 배열
 * @returns {T} 첫 번째 요소
 */
function first<T>(arr: T[]): T {
  return arr[0];
}

• @template T → 함수가 제네릭임을 나타냄
• 제네릭을 사용하는 함수에 필수

객체	{ name: string, age: number }	인라인 객체 타입
배열	string[] 또는 Array<string>	배열 타입
커스텀 타입	@typedef, @property	JS에서 타입 선언 + 사용
제네릭	@template T, @param {T[]}	타입 변수(T)를 가진 함수에 사용

---

3단계: 클래스 및 모듈 문서화

---

1. 클래스에 주석 달기 (@class)

/**
 * 사용자 계정을 관리하는 클래스
 * @class
 */
class UserAccount {
  /**
   * 사용자명
   * @type {string}
   */
  username: string;

  /**
   * 생성자
   * @param {string} username 사용자명
   */
  constructor(username: string) {
    this.username = username;
  }

  /**
   * 사용자명을 대문자로 반환
   * @returns {string}
   */
  getUpperName(): string {
    return this.username.toUpperCase();
  }
}

• @class: 클래스에 대한 전반적인 설명
• @constructor: 생략 가능 (ES6 class 문법 사용 시 암시적)
• @returns: 메서드 반환값 설명

---

2. 클래스 내부 this 타입 명시 (@this)

/**
 * @class
 */
function Counter() {
  /** @type {number} */
  this.value = 0;
}

/**
 * 값을 증가시킵니다.
 * @this {Counter}
 */
Counter.prototype.increment = function () {
  this.value++;
};

• 일반 함수로 작성된 생성자에서 @this 사용
• TS class에서는 대부분 생략 가능

---

3. 모듈 및 내보내기 (@module, @exports, @namespace)

/**
 * @module auth
 * 사용자 인증 관련 함수들을 포함한 모듈
 */

/**
 * 로그인 처리 함수
 * @param {string} email
 * @param {string} password
 * @returns {boolean}
 */
export function login(email: string, password: string): boolean {
  return true;
}

또는 CommonJS 스타일:

/**
 * @module utils/math
 */

/**
 * 더하기 함수
 * @function
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
exports.add = function (a, b) {
  return a + b;
};

• @module: 파일 또는 모듈 단위 설명
• @exports: 내보내는 객체에 주석을 추가
• @namespace: 네임스페이스를 명시할 때 (e.g., UMD 라이브러리용)

@class	클래스 선언 주석
@constructor	생성자 설명 (보통 생략 가능)
@method	메서드에 명시적으로 사용 가능 (옵션)
@this	생성자 함수에서 this 타입 지정
@module	모듈 전체 설명
@exports	모듈에서 내보내는 개체 설명 (CommonJS)
@namespace	글로벌 객체 네임스페이스 설명 (UMD 등)

---

4단계: JSDoc 자동 문서 생성 도구 사용

---

1. 도구 선택

JSDoc	가장 널리 쓰이는 도구, .js 중심	JavaScript
TypeDoc	TypeScript에 최적화된 문서화 도구	TypeScript

---

2. 설치 방법

JSDoc (JavaScript 중심)

npm install --save-dev jsdoc

TypeDoc (TypeScript 프로젝트 권장)

npm install --save-dev typedoc

---

3. 기본 사용법

JSDoc

npx jsdoc -r src -d docs

• -r: src 폴더를 재귀적으로 읽음
• -d: 결과물 HTML을 출력할 폴더

TypeDoc

npx typedoc src --out docs

---

4. 설정 파일 작성

.jsdoc.json (JSDoc 용)

{
  "source": {
    "include": ["src"],
    "includePattern": ".+\\.ts$"
  },
  "opts": {
    "destination": "docs",
    "recurse": true
  },
  "plugins": []
}

사용 예:

npx jsdoc -c .jsdoc.json

typedoc.json (TypeDoc 용)

{
  "entryPoints": ["src"],
  "out": "docs",
  "includeVersion": true,
  "excludePrivate": true
}

사용 예:

npx typedoc

---

5. package.json 스크립트 등록

"scripts": {
  "docs": "typedoc" // 또는 "jsdoc -c .jsdoc.json"
}

사용:

npm run docs

---

6. 문서 배포 (선택)

GitHub Pages에 배포 예:

npm install gh-pages --save-dev

"scripts": {
  "deploy-docs": "gh-pages -d docs"
}

---

5단계: 실습 및 자동화

---

1. 실습 과제

1.1. JSDoc 주석 적용

• 프로젝트 전체 코드에 JSDoc 또는 TypeDoc 주석 작성
• 함수, 클래스, 모듈, 타입, 인터페이스 등에 @param, @returns, @typedef, @example 등 적용

1.2. HTML 문서 생성

• docs/ 폴더에 HTML 문서 출력

# JSDoc
npx jsdoc -c jsdoc.config.json

# TypeDoc
npx typedoc

1.3. GitHub Pages로 수동 배포

npm install gh-pages --save-dev

"scripts": {
  "docs": "typedoc",
  "deploy-docs": "gh-pages -d docs"
}

npm run docs
npm run deploy-docs

---

2. GitHub Actions 자동화

Push할 때마다 최신 문서 자동 빌드 & 배포

2.1. .github/workflows/docs.yml 생성

name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Dependencies
        run: npm ci

      - name: Build Documentation
        run: npm run docs

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

2.2. 설정 요약

• npm run docs 실행 → docs/ 폴더 생성
• gh-pages 브랜치로 자동 커밋 후 배포
• 브랜치 설정에서 GitHub Pages를 gh-pages로 지정

---

3. 결과 확인

• https://your-username.github.io/your-repo-name/에서 문서 확인
• .nojekyll 파일이 없으면 일부 파일이 누락될 수 있으니 자동 생성 확인 필요

---

TypeScript + 문서화 학습 플랜

TypeDoc은 TypeScript 타입만으로도 문서를 추론하지만, 주석이 있다면 더 풍부하게 문서화됩니다.

---

6단계: TypeScript 타입 시스템 이해

---

1. 기본 타입 선언

• string, number, boolean, undefined, null

const name: string = 'Alice';
const age: number = 30;
const isActive: boolean = true;

---

2. 객체 타입 정의

2.1. interface vs type 비교 및 사용

interface User {
  id: number;
  name: string;
  email?: string; // optional
}

type Product = {
  id: string;
  title: string;
  price: number;
};

2.2. 함수 파라미터와 반환 타입으로 활용

function getUser(id: number): User {
  return { id, name: 'Kim' };
}

---

3. 함수 타입 명시

const greet: (name: string) => string = (name) => `Hello, ${name}`;

type LoginFn = (email: string, password: string) => boolean;

---

4. 고급 타입 패턴

4.1. Optional, Union, Intersection

type Status = 'idle' | 'loading' | 'error' | 'success';

interface APIResponse {
  status: Status;
  data?: any;
  error?: string;
}

4.2. 제네릭 (Generic)

function wrap<T>(value: T): { value: T } {
  return { value };
}

const wrapped = wrap<number>(123);

interface ApiResponse<T> {
  data: T;
  error?: string;
}

---

5. 유틸리티 타입 (읽기 전용, 선택적, 필수 등)

type ReadonlyUser = Readonly<User>;
type PartialUser = Partial<User>;
type RequiredUser = Required<User>;
type PickedUser = Pick<User, 'id' | 'name'>;

---

6. JS 문서보다 나은 TypeScript 문서화 예시

/**
 * 로그인 폼 정보
 */
interface LoginForm {
  email: string;
  password: string;
}

/**
 * 로그인 응답
 */
interface LoginResponse {
  accessToken: string;
  refreshToken: string;
}

위와 같은 코드만으로도 IDE 자동완성, 타입 추론, 문서 설명이 충분히 가능

---

7단계: JSDoc + TypeScript 병행 작성법

---

1. 함수 위에 JSDoc 주석 추가

/**
 * Adds two numbers and returns the result.
 * 
 * @param a - The first number
 * @param b - The second number
 * @returns Sum of a and b
 * @example
 * ```ts
 * add(2, 3); // 5
 * ```
 */
function add(a: number, b: number): number {
  return a + b;
}

TypeScript가 타입 추론을 해주더라도, @param / @returns는 의도 설명을 위해 여전히 유용합니다.

---

2. 클래스, 메서드, 속성에 JSDoc 추가

/**
 * Represents a user in the system.
 * @class
 */
class User {
  /**
   * Creates a new user.
   * @param name - The user's name
   * @param age - The user's age
   */
  constructor(public name: string, public age: number) {}

  /**
   * Returns a greeting message.
   * @returns A greeting string
   */
  greet(): string {
    return `Hello, ${this.name}`;
  }
}

constructor, method, field에도 목적이나 사용법을 설명하는 주석을 추가함으로써 유지보수성 향상

---

3. 커스텀 타입이나 유틸리티 타입에 설명 추가

/**
 * Represents an item in the cart.
 */
type CartItem = {
  id: string;
  name: string;
  quantity: number;
  price: number;
};

또는 interface도 동일하게:

/**
 * 로그인 요청 데이터 형식
 */
interface LoginRequest {
  /** 사용자 이메일 */
  email: string;
  /** 사용자 비밀번호 */
  password: string;
}

---

4. @example 태그로 사용법 명시

/**
 * 로그 메시지를 출력합니다.
 *
 * @param message - 출력할 메시지
 * @example
 * ```ts
 * logMessage("Hello, world!");
 * ```
 */
function logMessage(message: string): void {
  console.log(message);
}

---

5. 병행 사용 시 팁

• 타입 선언은 TypeScript에 맡기고, JSDoc은 목적 설명, 예제, 주의사항 중심으로 작성
• @param, @returns는 생략 가능하지만 복잡하거나 비표준적인 로직일 경우 명시 권장
• IDE (VS Code 등)는 JSDoc 주석을 자동 툴팁으로 보여주므로 간결하면서도 명확하게

---

8단계: TypeDoc으로 HTML 문서 생성

---

1. TypeDoc이란?

• TypeScript용 문서 생성기
• TS 타입 정보를 분석해서 자동으로 HTML 문서 생성
• JSDoc 주석도 인식하여 풍부한 문서 제공

TypeDoc

---

2. 설치

npm install --save-dev typedoc

또는 전역 설치:

npm install -g typedoc

---

3. 가장 기본적인 실행 예시

npx typedoc --entryPoints src/index.ts --out docs

• --entryPoints: 문서화 시작 지점 파일 (보통 src/index.ts)
• --out: HTML 문서를 생성할 디렉토리 (예: docs/)

---

4. 주요 옵션 정리

--entryPoints	문서 생성을 시작할 진입 파일 (필수)
--out	HTML 문서 출력 경로
--tsconfig	사용자 정의 tsconfig.json 경로 지정
--excludePrivate	private 키워드가 붙은 멤버 제외
--excludeProtected	protected 멤버 제외
--excludeInternal	@internal 태그가 붙은 요소 제외
--includeVersion	문서에 프로젝트 버전 포함 (package.json 기준)
--theme	커스텀 테마 적용 (기본: default)

---

5. 실전 명령어

npx typedoc \
  --entryPoints src/index.ts \
  --out docs \
  --tsconfig tsconfig.json \
  --excludePrivate \
  --excludeProtected \
  --includeVersion

---

6. typedoc.json 설정 파일 만들기 (선택)

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "tsconfig": "tsconfig.json",
  "excludePrivate": true,
  "excludeProtected": true,
  "includeVersion": true
}

실행은 간단히:

npx typedoc

---

7. VS Code 연동 팁

• docs/ 폴더를 .gitignore에 포함하지 않으면 GitHub Pages 배포 가능
• 생성된 docs/index.html을 브라우저로 열면 미리보기 가능

---

9단계: GitHub Pages로 TypeDoc 문서 배포하기

---

1. 문서를 /docs 폴더에 출력

TypeDoc 실행 시 다음과 같이 docs/ 폴더로 출력:

npx typedoc --entryPoints src/index.ts --out docs

또는 typedoc.json에 설정:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs"
}

---

2. GitHub Pages에 필요한 설정 추가

package.json 수정:

{
  "name": "your-project",
  "homepage": "https://<username>.github.io/<repository-name>",
  "scripts": {
    "docs": "typedoc",
    "predeploy": "npm run docs",
    "deploy": "gh-pages -d docs"
  }
}

---

3. gh-pages 라이브러리 설치

npm install --save-dev gh-pages

이 라이브러리는 docs/ 폴더를 gh-pages 브랜치로 자동 배포하는 데 사용됩니다.

---

4. GitHub Pages 설정

1. GitHub 저장소 > Settings > Pages로 이동
2. Source: Deploy from a branch
3. Branch: gh-pages 선택
   Folder: / (root) 또는 docs는 필요 없음 (gh-pages 브랜치에 전체 배포됨)

---

5. 배포 실행

npm run deploy

실행 순서:

• predeploy → npm run docs 로 HTML 생성
• deploy → gh-pages -d docs 로 gh-pages 브랜치에 업로드

---

6. 결과 확인

• URL: https://<username>.github.io/<repository-name>/

배포 직후엔 1~2분 정도 시간이 걸릴 수 있습니다.
리포지토리가 공개(public)여야 정상 동작합니다.

---

10단계: 자동화 및 실전 프로젝트 적용

---

1. GitHub Actions로 문서 자동화

main 브랜치에 push되면 TypeDoc을 실행하고 gh-pages 브랜치로 문서 자동 배포

작업 순서

1. .github/workflows/typedoc.yml 생성:

name: Deploy Docs

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Generate docs
        run: npm run docs

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

1. docs 스크립트는 typedoc 실행이어야 함:

"scripts": {
  "docs": "typedoc"
}

1. GitHub Pages 설정에서 gh-pages 브랜치로 설정

---

2. Jenkins로 문서 자동화

사내 서버 또는 팀 빌드 서버가 있을 경우 활용

Jenkins 작업 예시

1. Git pull (Trigger: webhook or cron)
2. npm ci 또는 yarn install
3. npm run docs 로 문서 생성
4. scp, rsync, FTP 등으로 docs/ 폴더를 웹 서버나 정적 페이지 서버로 업로드

예: Jenkinsfile 내 Shell Script

stage('Generate Docs') {
  steps {
    sh 'npm ci'
    sh 'npm run docs'
    sh 'rsync -avz docs/ user@server:/var/www/docs'
  }
}

---

3. 팀용 도큐먼트 시스템 구축

TypeDoc 외에 보다 직관적인 문서 시스템이 필요한 경우:

• Docusaurus + TypeDoc 연동
  → 개발 문서 + API 문서를 함께 관리 가능
• Storybook + JSDoc
  → UI 컴포넌트 문서화 + 인터랙티브 데모

---

 

JSDoc → TypeScript 전환 가이드 (함수 중심)

1. 기본 JSDoc 구조 이해

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

설명:

• @param {number} a → a의 타입이 number임을 문서화
• @returns {number} → 함수가 number를 반환함을 명시

이 구조는 자바스크립트 코드에 타입 정보를 추가해서 IDE가 도와주도록 하기 위한 것입니다.
하지만 TypeScript를 사용하면 이 정보를 정적으로 타입 시스템에 통합할 수 있습니다.

---

2. JSDoc → TypeScript: 직접 타입 선언으로 대체

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

전환 포인트 분석:

JS 코드 요소 | JSDoc 방식 | TypeScript 방식 | 설명

매개변수 타입 지정	@param {number}	a: number	타입 추론이 아니라 명시적
반환 타입 지정	@returns {number}	): number	함수 시그니처에서 직접
함수 설명	주석 그대로 유지	/** ... */ 블록 그대로 사용	의미 해석 목적

※ @param과 @returns는 문서화 목적만 남고, 정적 타입 검사 목적은 없어짐

---

3. 불필요한 {타입} 제거

TypeScript로 전환했을 경우 JSDoc의 {타입} 부분은 중복되므로 생략 가능합니다.

/**
 * 두 숫자를 더합니다.
 * @param a 첫 번째 숫자
 * @param b 두 번째 숫자
 * @returns 합계
 */

→ {number}는 TypeScript 타입 시스템이 대체하기 때문에 제거

단, 설명 (첫 번째 숫자) 등은 유지해야 합니다.

---

4. JSDoc이 여전히 필요한 이유

• 문서화 용도: HTML 문서 생성 시 사용
• JS/TS 둘 다에서 호환 가능
• 타입이 너무 복잡한 경우 설명 보완 용도

/**
 * 유저 목록을 페이지네이션과 함께 불러옵니다.
 * @param page 요청할 페이지 번호 (1부터 시작)
 * @param size 한 페이지당 항목 수
 * @returns 유저 목록과 총 개수 정보
 */
function fetchUsers(page: number, size: number): Promise<UserListResponse> {
  ...
}

→ 설명은 여전히 유효. 타입은 TS가 대체.

---

5. 다양한 사례

배열

/**
 * 숫자 배열의 합계를 구합니다.
 * @param {number[]} nums - 숫자 배열
 * @returns {number}
 */
function sum(nums) {
  return nums.reduce((a, b) => a + b, 0);
}

⬇️ TypeScript 전환:

/**
 * 숫자 배열의 합계를 구합니다.
 * @param nums 숫자 배열
 * @returns 합계
 */
function sum(nums: number[]): number {
  return nums.reduce((a, b) => a + b, 0);
}

---

객체

/**
 * 유저의 전체 이름을 반환합니다.
 * @param {{ firstName: string, lastName: string }} user
 * @returns {string}
 */
function getFullName(user) {
  return `${user.firstName} ${user.lastName}`;
}

⬇️ TypeScript 전환:

interface User {
  firstName: string;
  lastName: string;
}

/**
 * 유저의 전체 이름을 반환합니다.
 * @param user 유저 정보
 * @returns 전체 이름
 */
function getFullName(user: User): string {
  return `${user.firstName} ${user.lastName}`;
}

---

6. 추천 전략

타입 검증 / IDE 지원	TypeScript 타입 사용
코드 이해를 돕는 설명	JSDoc @param, @returns 유지
외부 문서 생성	JSDoc 유지 (Typedoc 등)

---

JSDoc + TypeScript 시그니처 조합: 베스트 프랙티스

---

1. 함수(Function) 주석 템플릿

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

---

2. 비동기 함수 (Async Function)

/**
 * 사용자 정보를 서버에서 불러옵니다.
 * @param userId - 사용자 고유 ID
 * @returns 사용자 정보 Promise
 * @throws 네트워크 오류가 발생할 수 있습니다.
 */
export async function fetchUser(userId: string): Promise<User> {
  const res = await fetch(`/api/users/${userId}`);
  if (!res.ok) throw new Error('Failed to fetch user');
  return res.json();
}

---

3. 클래스(Class) 주석

/**
 * 사용자 관련 기능을 제공하는 클래스입니다.
 * @class
 * @example
 * ```ts
 * const service = new UserService();
 * const user = service.getUserById('abc123');
 * ```
 */
export class UserService {
  /**
   * ID로 유저를 조회합니다.
   * @param id - 유저 ID
   * @returns 유저 객체
   */
  getUserById(id: string): User {
    // ...
  }

  /**
   * @deprecated 더 이상 사용되지 않으며, getUserById를 사용하세요.
   */
  getUser(id: string): User {
    return this.getUserById(id);
  }
}

---

4. 타입 / 인터페이스 정의

/**
 * 사용자 정보 타입
 * @typedef {Object} User
 * @property {string} id - 사용자 고유 ID
 * @property {string} name - 사용자 이름
 * @property {number} age - 나이
 */
export interface User {
  id: string;
  name: string;
  age: number;
}

---

5. 제네릭(Generic) 함수 주석

/**
 * 주어진 값을 배열로 감쌉니다.
 * @template T
 * @param value - 감쌀 값
 * @returns 값이 포함된 배열
 */
export function wrapInArray<T>(value: T): T[] {
  return [value];
}

---

6. 네임스페이스 / 모듈 단위 주석

/**
 * @module utils/math
 * 수학 유틸리티 함수들을 모은 모듈입니다.
 */

또는 ES 모듈 환경에서는 실제 모듈 경로가 곧 문서화 이름이 되므로 생략 가능합니다.

---

7. Deprecated 태그

/**
 * @deprecated 이 함수는 v2에서 제거됩니다. 대신 `getDataV2`를 사용하세요.
 */
export function getData() {
  // ...
}

---

8. 리터럴과 코드 강조

/**
 * 사용자 권한 값입니다.
 * @type {'ADMIN' | 'USER'}
 * @readonly
 * @example
 * ```ts
 * if (role === 'ADMIN') { ... }
 * ```
 */
export type UserRole = 'ADMIN' | 'USER';

---

9. 모듈 유틸 함수 예시

/**
 * 쿠키 값을 읽어옵니다.
 * @param name - 쿠키 이름
 * @returns 쿠키 값 또는 null
 */
export function getCookie(name: string): string | null {
  // ...
}

---

10. React 컴포넌트 주석 예시

/**
 * 사용자 아바타 컴포넌트
 * @param props 사용자 객체
 * @returns JSX 엘리먼트
 */
export function UserAvatar({ user }: { user: User }) {
  return <img src={user.avatarUrl} alt={`${user.name}의 아바타`} />;
}

---

11. 고급 예제: 실무에서 유용한 태그 활용

/**
 * 유저를 생성합니다.
 *
 * @deprecated 이 함수는 `createUserV2`로 대체되었습니다.
 * @see createUserV2
 * @param user 유저 정보 객체
 * @returns 생성된 유저의 ID
 * @example
 * ```ts
 * const id = createUser({ name: 'Alice', age: 30 });
 * ```
 */
export function createUser(user: { name: string; age: number }): string {
  // ...
  return 'user-id';
}

각 태그의 역할:

• @deprecated: 사용 중단 안내 + 대체 함수 링크
• @see: 연결될 관련 API, 클래스, 문서 등 링크
• @example: 사용 예시 (문서 생성기에서 코드 블록으로 렌더링됨)

---

12. 클래스/메서드 예제

/**
 * 유저를 관리하는 서비스 클래스입니다.
 * @since 1.0.0
 */
export class UserService {
  /**
   * 유저 ID로 유저 정보를 조회합니다.
   * @param id 유저의 고유 ID
   * @returns 유저 객체
   */
  getUserById(id: string): User {
    // ...
  }

  /**
   * @deprecated 대신 `updateUserProfile`을 사용하세요.
   */
  updateUser(user: User): void {
    // ...
  }
}

---

문서 생성까지 연결: Typedoc / JSDoc

TypeDoc (TypeScript 전용)

설치:

npm install --save-dev typedoc

명령어:

npx typedoc --entryPoints src/index.ts --out docs

주요 옵션:

• --tsconfig tsconfig.json
• --excludePrivate, --includeVersion
• --readme none → 루트 README 무시

---

JSDoc (TS/JS 모두 지원, 유연하지만 TS 완전 지원은 낮음)

설치:

npm install --save-dev jsdoc

명령어:

npx jsdoc -r src -d docs

설정 파일 (.jsdoc.json) 예시:

{
  "source": {
    "include": ["src"],
    "includePattern": ".+\\.ts(doc|x)?$"
  },
  "opts": {
    "destination": "./docs",
    "recurse": true,
    "template": "default"
  }
}

---

GitHub Pages에 문서 배포하기

1. /docs 폴더에 HTML 생성
2. package.json에 script 추가:

"scripts": {
  "docs": "typedoc",
  "deploy-docs": "gh-pages -d docs"
}

1. gh-pages 패키지 설치:

npm install gh-pages --save-dev

1. GitHub Pages → Settings > Pages 에서 docs 경로 또는 gh-pages 브랜치 선택