🎯 왜 문서화가 중요할까?

📝 TSDoc이란 무엇인가?

🔍 TSDoc의 핵심 특징

💻 기본 TSDoc 문법

/**
 * 두 숫자를 더하는 함수입니다.
 * 
 * @param a - 첫 번째 숫자
 * @param b - 두 번째 숫자
 * @returns 두 숫자의 합
 * 
 * @example
 * ```typescript
 * const result = add(5, 3);
 * console.log(result); // 8
 * ```
 */
function add(a: number, b: number): number {
  return a + b;
}

🏷️ 주요 TSDoc 태그 완벽 가이드

📌 기본 태그

🔧 @param 태그 상세 활용

/**
 * 사용자 정보를 업데이트합니다.
 * 
 * @param userId - 업데이트할 사용자의 고유 식별자
 * @param data - 업데이트할 데이터 객체
 * @param data.name - 사용자 이름 (선택사항)
 * @param data.email - 이메일 주소 (선택사항)
 * @param options - 추가 옵션
 * @param options.validateEmail - 이메일 유효성 검사 여부 (기본값: true)
 */
function updateUser(
  userId: string,
  data: { name?: string; email?: string },
  options?: { validateEmail?: boolean }
): void {
  // 구현 코드
}

📤 @returns 태그 활용

/**
 * 사용자를 검색합니다.
 * 
 * @param query - 검색 쿼리
 * @returns 검색된 사용자 배열. 결과가 없으면 빈 배열을 반환합니다.
 *          각 사용자 객체는 id, name, email 속성을 포함합니다.
 */
async function searchUsers(query: string): Promise<User[]> {
  // 구현 코드
}

⚠️ @throws 태그로 예외 문서화

/**
 * 파일을 읽어서 JSON으로 파싱합니다.
 * 
 * @param filePath - 읽을 파일 경로
 * @returns 파싱된 JSON 객체
 * @throws {FileNotFoundError} 파일이 존재하지 않을 때
 * @throws {ParseError} JSON 파싱에 실패했을 때
 * @throws {PermissionError} 파일 읽기 권한이 없을 때
 */
function readJsonFile(filePath: string): object {
  // 구현 코드
}

📚 @example 태그로 사용법 보여주기

/**
 * 배열에서 중복을 제거합니다.
 * 
 * @param array - 중복을 제거할 배열
 * @returns 중복이 제거된 새 배열
 * 
 * @example
 * 기본 사용법:
 * ```typescript
 * const numbers = [1, 2, 2, 3, 3, 3, 4];
 * const unique = removeDuplicates(numbers);
 * console.log(unique); // [1, 2, 3, 4]
 * ```
 * 
 * @example
 * 객체 배열에서 사용:
 * ```typescript
 * const users = [
 *   { id: 1, name: 'Alice' },
 *   { id: 1, name: 'Alice' },
 *   { id: 2, name: 'Bob' }
 * ];
 * const uniqueUsers = removeDuplicates(users);
 * // [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
 * ```
 */
function removeDuplicates<T>(array: T[]): T[] {
  return Array.from(new Set(array));
}

🎨 고급 TSDoc 기법

🔗 @see 태그로 관련 항목 연결

/**
 * 사용자를 생성합니다.
 * 
 * @param userData - 생성할 사용자 데이터
 * @returns 생성된 사용자 객체
 * 
 * @see {@link updateUser} - 사용자 정보 업데이트
 * @see {@link deleteUser} - 사용자 삭제
 * @see https://docs.example.com/user-management - 사용자 관리 가이드
 */
function createUser(userData: UserData): User {
  // 구현 코드
}

📦 @typeParam으로 제네릭 타입 설명

/**
 * 배열의 각 요소를 변환합니다.
 * 
 * @typeParam T - 입력 배열의 요소 타입
 * @typeParam U - 출력 배열의 요소 타입
 * @param array - 변환할 배열
 * @param mapper - 각 요소를 변환하는 함수
 * @returns 변환된 새 배열
 * 
 * @example
 * ```typescript
 * const numbers = [1, 2, 3];
 * const strings = map(numbers, n => n.toString());
 * // ['1', '2', '3']
 * ```
 */
function map<T, U>(array: T[], mapper: (item: T) => U): U[] {
  return array.map(mapper);
}

🏷️ @deprecated로 사용 중단 표시

/**
 * 사용자 목록을 가져옵니다.
 * 
 * @deprecated 이 함수는 v2.0에서 제거될 예정입니다.
 *             대신 {@link getUsersPaginated}를 사용하세요.
 * 
 * @returns 모든 사용자 배열
 */
function getUsers(): User[] {
  // 구현 코드
}

/**
 * 페이지네이션을 지원하는 사용자 목록을 가져옵니다.
 * 
 * @param page - 페이지 번호 (1부터 시작)
 * @param limit - 페이지당 항목 수
 * @returns 페이지네이션된 사용자 목록
 */
function getUsersPaginated(page: number, limit: number): PaginatedUsers {
  // 구현 코드
}

🎭 @internal로 내부 API 표시

/**
 * @internal
 * 내부적으로 사용되는 헬퍼 함수입니다.
 * 외부에서 직접 호출하지 마세요.
 */
function _internalHelper(): void {
  // 구현 코드
}

📝 마크다운 활용하기

/**
 * 복잡한 데이터 처리 함수입니다.
 * 
 * @remarks
 * 이 함수는 다음 단계로 데이터를 처리합니다:
 * 
 * 1. **검증**: 입력 데이터의 유효성 검사
 * 2. **변환**: 데이터를 내부 형식으로 변환
 * 3. **처리**: 비즈니스 로직 적용
 * 4. **반환**: 결과 데이터 반환
 * 
 * > **중요**: 이 함수는 비동기로 동작하므로 반드시 await를 사용해야 합니다.
 * 
 * 성능 고려사항:
 * - 대용량 데이터(>10MB)는 스트리밍 방식을 사용하세요
 * - 병렬 처리가 필요하면 `processDataParallel()`을 사용하세요
 * 
 * @param data - 처리할 데이터
 * @returns 처리된 결과
 */
async function processData(data: RawData): Promise<ProcessedData> {
  // 구현 코드
}

🛠️ API 문서 자동 생성 도구들

📘 TypeDoc - 가장 인기 있는 선택

TypeDoc 설치 및 설정

# TypeDoc 설치
npm install --save-dev typedoc

# 기본 문서 생성
npx typedoc src/index.ts

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "name": "My Awesome Library",
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeExternals": true,
  "readme": "README.md",
  "theme": "default",
  "includeVersion": true,
  "categorizeByGroup": true,
  "sort": ["source-order"]
}

{
  "scripts": {
    "docs": "typedoc",
    "docs:watch": "typedoc --watch"
  }
}

📗 API Extractor + API Documenter

API Extractor 설정

# 설치
npm install --save-dev @microsoft/api-extractor @microsoft/api-documenter

# 설정 파일 생성
npx api-extractor init

{
  "mainEntryPointFilePath": "dist/index.d.ts",
  "apiReport": {
    "enabled": true,
    "reportFolder": "temp"
  },
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "temp/<unscopedPackageName>.api.json"
  },
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "dist/index.d.ts"
  }
}

# 1. API 모델 추출
npx api-extractor run --local

# 2. 문서 생성
npx api-documenter markdown -i temp -o docs

📙 TSDoc 파서 직접 사용하기

import { TSDocParser } from '@microsoft/tsdoc';
import * as ts from 'typescript';

const parser = new TSDocParser();

function extractDocumentation(sourceFile: ts.SourceFile) {
  ts.forEachChild(sourceFile, node => {
    if (ts.isFunctionDeclaration(node) && node.name) {
      const jsDocComments = ts.getJSDocCommentsAndTags(node);
      
      jsDocComments.forEach(comment => {
        const text = comment.comment || '';
        const parserContext = parser.parseString(text.toString());
        
        console.log('Function:', node.name?.text);
        console.log('Summary:', parserContext.docComment.summarySection);
      });
    }
  });
}

🎯 실전 프로젝트 적용 사례

🏗️ 클래스 문서화

/**
 * 사용자 관리를 담당하는 서비스 클래스입니다.
 * 
 * @remarks
 * 이 클래스는 싱글톤 패턴으로 구현되어 있습니다.
 * `getInstance()` 메서드를 통해 인스턴스를 얻어야 합니다.
 * 
 * @example
 * ```typescript
 * const userService = UserService.getInstance();
 * const user = await userService.createUser({
 *   name: 'Alice',
 *   email: 'alice@example.com'
 * });
 * ```
 */
export class UserService {
  /**
   * 서비스의 싱글톤 인스턴스
   * @internal
   */
  private static instance: UserService;

  /**
   * 사용자 데이터를 저장하는 저장소
   */
  private readonly repository: UserRepository;

  /**
   * @internal
   * 생성자는 private으로 선언되어 외부에서 직접 호출할 수 없습니다.
   */
  private constructor() {
    this.repository = new UserRepository();
  }

  /**
   * UserService의 싱글톤 인스턴스를 반환합니다.
   * 
   * @returns UserService 인스턴스
   */
  public static getInstance(): UserService {
    if (!UserService.instance) {
      UserService.instance = new UserService();
    }
    return UserService.instance;
  }

  /**
   * 새로운 사용자를 생성합니다.
   * 
   * @param userData - 생성할 사용자의 정보
   * @param userData.name - 사용자 이름 (2-50자)
   * @param userData.email - 이메일 주소 (유효한 형식이어야 함)
   * @param userData.age - 나이 (선택사항, 0-150)
   * @returns 생성된 사용자 객체
   * 
   * @throws {ValidationError} 입력 데이터가 유효하지 않을 때
   * @throws {DuplicateError} 이미 존재하는 이메일일 때
   * 
   * @example
   * ```typescript
   * const user = await userService.createUser({
   *   name: 'Bob',
   *   email: 'bob@example.com',
   *   age: 25
   * });
   * console.log(user.id); // 생성된 사용자 ID
   * ```
   */
  public async createUser(userData: CreateUserDto): Promise<User> {
    // 구현 코드
  }

  /**
   * ID로 사용자를 조회합니다.
   * 
   * @param userId - 조회할 사용자의 ID
   * @returns 사용자 객체 또는 null (사용자가 없을 경우)
   * 
   * @example
   * ```typescript
   * const user = await userService.getUserById('user-123');
   * if (user) {
   *   console.log(user.name);
   * } else {
   *   console.log('사용자를 찾을 수 없습니다');
   * }
   * ```
   */
  public async getUserById(userId: string): Promise<User | null> {
    // 구현 코드
  }
}

🔧 인터페이스와 타입 문서화

/**
 * 사용자 정보를 나타내는 인터페이스입니다.
 * 
 * @remarks
 * 이 인터페이스는 데이터베이스 스키마와 1:1로 매핑됩니다.
 * 모든 필드는 데이터베이스에 저장되는 값과 동일한 형식을 유지합니다.
 */
export interface User {
  /**
   * 사용자의 고유 식별자
   * @remarks UUID v4 형식을 사용합니다
   */
  id: string;

  /**
   * 사용자 이름
   * @remarks 2-50자 사이여야 하며, 특수문자는 허용되지 않습니다
   */
  name: string;

  /**
   * 이메일 주소
   * @remarks 유일해야 하며, 유효한 이메일 형식이어야 합니다
   */
  email: string;

  /**
   * 계정 생성 일시
   * @remarks ISO 8601 형식의 타임스탬프
   */
  createdAt: Date;

  /**
   * 마지막 로그인 일시
   * @remarks 한 번도 로그인하지 않은 경우 null
   */
  lastLoginAt: Date | null;
}

/**
 * 사용자 생성 시 필요한 데이터 전송 객체입니다.
 * 
 * @remarks
 * 이 타입은 {@link User} 인터페이스에서 시스템이 자동으로 생성하는
 * 필드들(id, createdAt 등)을 제외한 것입니다.
 */
export type CreateUserDto = Pick<User, 'name' | 'email'> & {
  /**
   * 초기 비밀번호
   * @remarks 최소 8자 이상, 영문/숫자/특수문자 조합
   */
  password: string;
};

/**
 * 페이지네이션 결과를 나타내는 제네릭 타입입니다.
 * 
 * @typeParam T - 페이지네이션할 데이터의 타입
 * 
 * @example
 * ```typescript
 * const result: PaginatedResult<User> = {
 *   items: [user1, user2, user3],
 *   total: 100,
 *   page: 1,
 *   pageSize: 10
 * };
 * ```
 */
export interface PaginatedResult<T> {
  /** 현재 페이지의 항목들 */
  items: T[];
  
  /** 전체 항목 수 */
  total: number;
  
  /** 현재 페이지 번호 (1부터 시작) */
  page: number;
  
  /** 페이지당 항목 수 */
  pageSize: number;
  
  /** 전체 페이지 수 */
  get totalPages(): number;
  
  /** 다음 페이지 존재 여부 */
  get hasNext(): boolean;
  
  /** 이전 페이지 존재 여부 */
  get hasPrevious(): boolean;
}

🎨 React 컴포넌트 문서화

/**
 * 사용자 프로필 카드 컴포넌트입니다.
 * 
 * @remarks
 * 이 컴포넌트는 사용자의 기본 정보를 카드 형태로 표시합니다.
 * 아바타, 이름, 이메일, 그리고 선택적으로 추가 정보를 보여줄 수 있습니다.
 * 
 * @example
 * 기본 사용법:
 * ```tsx
 * <UserProfileCard
 *   user={currentUser}
 *   onEdit={() => handleEdit(currentUser.id)}
 * />
 * ```
 * 
 * @example
 * 추가 정보와 함께:
 * ```tsx
 * <UserProfileCard
 *   user={currentUser}
 *   showBio
 *   showJoinDate
 *   variant="detailed"
 * />
 * ```
 */
export const UserProfileCard: React.FC<UserProfileCardProps> = (props) => {
  // 구현 코드
};

/**
 * UserProfileCard 컴포넌트의 Props 인터페이스입니다.
 */
export interface UserProfileCardProps {
  /**
   * 표시할 사용자 객체
   */
  user: User;

  /**
   * 카드의 표시 스타일
   * @defaultValue 'compact'
   */
  variant?: 'compact' | 'detailed' | 'minimal';

  /**
   * 사용자 소개를 표시할지 여부
   * @defaultValue false
   */
  showBio?: boolean;

  /**
   * 가입 날짜를 표시할지 여부
   * @defaultValue false
   */
  showJoinDate?: boolean;

  /**
   * 편집 버튼 클릭 시 호출되는 콜백
   * @param userId - 편집할 사용자의 ID
   */
  onEdit?: (userId: string) => void;

  /**
   * 삭제 버튼 클릭 시 호출되는 콜백
   * @param userId - 삭제할 사용자의 ID
   */
  onDelete?: (userId: string) => void;

  /**
   * 추가 CSS 클래스명
   */
  className?: string;

  /**
   * 인라인 스타일
   */
  style?: React.CSSProperties;
}

🔌 유틸리티 함수 모음 문서화

/**
 * 문자열 처리 유틸리티 함수 모음입니다.
 * 
 * @remarks
 * 이 모듈은 일반적인 문자열 조작 작업을 위한 헬퍼 함수들을 제공합니다.
 * 모든 함수는 순수 함수로 구현되어 있으며, 원본 문자열을 변경하지 않습니다.
 * 
 * @packageDocumentation
 */

/**
 * 문자열의 첫 글자를 대문자로 변환합니다.
 * 
 * @param str - 변환할 문자열
 * @returns 첫 글자가 대문자로 변환된 문자열
 * 
 * @example
 * ```typescript
 * capitalize('hello'); // 'Hello'
 * capitalize('WORLD'); // 'WORLD'
 * capitalize(''); // ''
 * ```
 */
export function capitalize(str: string): string {
  if (!str) return str;
  return str.charAt(0).toUpperCase() + str.slice(1);
}

/**
 * 카멜케이스 문자열을 케밥케이스로 변환합니다.
 * 
 * @param str - 변환할 카멜케이스 문자열
 * @returns 케밥케이스로 변환된 문자열
 * 
 * @example
 * ```typescript
 * camelToKebab('userName'); // 'user-name'
 * camelToKebab('getUserById'); // 'get-user-by-id'
 * camelToKebab('API'); // 'a-p-i'
 * ```
 */
export function camelToKebab(str: string): string {
  return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
}

/**
 * 문자열을 지정된 길이로 자르고 말줄임표를 추가합니다.
 * 
 * @param str - 자를 문자열
 * @param maxLength - 최대 길이 (말줄임표 포함)
 * @param ellipsis - 말줄임표 문자 (기본값: '...')
 * @returns 잘린 문자열
 * 
 * @throws {Error} maxLength가 ellipsis 길이보다 작을 때
 * 
 * @example
 * ```typescript
 * truncate('Hello World', 8); // 'Hello...'
 * truncate('Short', 10); // 'Short'
 * truncate('Long text here', 10, '…'); // 'Long text…'
 * ```
 */
export function truncate(
  str: string,
  maxLength: number,
  ellipsis: string = '...'
): string {
  if (maxLength < ellipsis.length) {
    throw new Error('maxLength must be greater than ellipsis length');
  }
  if (str.length <= maxLength) return str;
  return str.slice(0, maxLength - ellipsis.length) + ellipsis;
}

✨ 문서화 베스트 프랙티스

📋 일관성 유지하기

🎯 명확하고 간결하게

// ❌ 나쁜 예: 너무 장황함
/**
 * 이 함수는 사용자가 제공한 두 개의 숫자를 받아서
 * 그것들을 더한 다음에 그 결과값을 반환하는 기능을
 * 수행합니다. 이 함수는 매우 간단하지만 유용하게
 * 사용될 수 있습니다.
 */
function add(a: number, b: number): number {
  return a + b;
}

// ✅ 좋은 예: 명확하고 간결함
/**
 * 두 숫자를 더합니다.
 * 
 * @param a - 첫 번째 숫자
 * @param b - 두 번째 숫자
 * @returns 두 숫자의 합
 */
function add(a: number, b: number): number {
  return a + b;
}

📚 예제는 필수!

🔄 문서를 최신 상태로 유지

// 코드 리뷰 체크리스트에 문서 업데이트 포함
// .github/pull_request_template.md

## 체크리스트
- [ ] 코드 변경사항이 문서에 반영되었나요?
- [ ] 새로운 공개 API에 TSDoc 주석이 추가되었나요?
- [ ] 예제 코드가 최신 API와 호환되나요?
- [ ] 변경된 파라미터나 반환값이 문서화되었나요?

⚠️ 중요한 정보는 강조하기

/**
 * 대용량 파일을 처리합니다.
 * 
 * @remarks
 * ⚠️ **중요**: 이 함수는 메모리에 전체 파일을 로드합니다.
 * 10MB 이상의 파일은 `processLargeFileStream()`을 사용하세요.
 * 
 * 💡 **팁**: 병렬 처리가 필요하면 `processFileParallel()`을 고려하세요.
 * 
 * @param filePath - 처리할 파일 경로
 * @returns 처리 결과
 * 
 * @see {@link processLargeFileStream} - 대용량 파일용 스트리밍 버전
 */
function processFile(filePath: string): ProcessResult {
  // 구현 코드
}

🔗 관련 항목 연결하기

/**
 * 사용자를 생성합니다.
 * 
 * @see {@link updateUser} - 사용자 정보 수정
 * @see {@link deleteUser} - 사용자 삭제
 * @see {@link getUserById} - 사용자 조회
 * @see {@link User} - 사용자 인터페이스
 */
function createUser(data: CreateUserDto): Promise<User> {
  // 구현 코드
}

🎨 코드 스타일 가이드 통합

# eslint-plugin-tsdoc 설치
npm install --save-dev eslint-plugin-tsdoc

# .eslintrc.json 설정
{
  "plugins": ["eslint-plugin-tsdoc"],
  "rules": {
    "tsdoc/syntax": "warn"
  }
}

🚀 CI/CD 파이프라인에 문서 생성 통합하기

📦 GitHub Actions로 자동 배포

# .github/workflows/docs.yml
name: Generate and Deploy Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build project
        run: npm run build
      
      - name: Generate documentation
        run: npm run docs
      
      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
          cname: docs.yourproject.com

🔍 문서 품질 검사

# .github/workflows/docs-check.yml
name: Documentation Quality Check

on: [pull_request]

jobs:
  check-docs:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Check TSDoc syntax
        run: npm run lint
      
      - name: Generate docs (dry run)
        run: npm run docs -- --dry-run
      
      - name: Check for undocumented exports
        run: |
          npm run docs -- --validation.notDocumented
      
      - name: Comment PR with results
        uses: actions/github-script@v6
        if: failure()
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '⚠️ 문서화 검사에 실패했습니다. 모든 공개 API에 TSDoc 주석을 추가해주세요!'
            })

📊 문서 커버리지 측정

// scripts/check-docs-coverage.ts
import * as ts from 'typescript';
import * as fs from 'fs';

interface CoverageStats {
  total: number;
  documented: number;
  percentage: number;
}

function checkDocsCoverage(fileNames: string[]): CoverageStats {
  const program = ts.createProgram(fileNames, {});
  let total = 0;
  let documented = 0;

  for (const sourceFile of program.getSourceFiles()) {
    if (sourceFile.fileName.includes('node_modules')) continue;

    ts.forEachChild(sourceFile, node => {
      if (isExportedDeclaration(node)) {
        total++;
        if (hasDocComment(node)) {
          documented++;
        }
      }
    });
  }

  return {
    total,
    documented,
    percentage: total > 0 ? (documented / total) * 100 : 0
  };
}

function isExportedDeclaration(node: ts.Node): boolean {
  return (
    (ts.isFunctionDeclaration(node) ||
     ts.isClassDeclaration(node) ||
     ts.isInterfaceDeclaration(node) ||
     ts.isTypeAliasDeclaration(node)) &&
    node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword)
  );
}

function hasDocComment(node: ts.Node): boolean {
  const comments = ts.getLeadingCommentRanges(
    node.getSourceFile().getFullText(),
    node.getFullStart()
  );
  return comments?.some(c => c.kind === ts.SyntaxKind.MultiLineCommentTrivia) ?? false;
}

// 실행
const stats = checkDocsCoverage(['src/**/*.ts']);
console.log(`문서화 커버리지: ${stats.percentage.toFixed(2)}%`);
console.log(`(${stats.documented}/${stats.total} 항목)`);

if (stats.percentage < 80) {
  console.error('❌ 문서화 커버리지가 80% 미만입니다!');
  process.exit(1);
}

🌐 다양한 플랫폼에 배포

🎓 실무에서 마주치는 문제들과 해결책

❓ 문제 1: 레거시 코드 문서화

// 우선순위 기반 문서화 체크리스트
// docs-priority.md

## Phase 1: 핵심 공개 API (1주차)
- [ ] User 관련 함수들
- [ ] Authentication 모듈
- [ ] 주요 유틸리티 함수

## Phase 2: 자주 사용되는 내부 API (2주차)
- [ ] Database 헬퍼
- [ ] Validation 함수들
- [ ] Error 핸들링

## Phase 3: 나머지 코드 (3-4주차)
- [ ] 테스트 유틸리티
- [ ] 설정 관련 코드
- [ ] 기타 헬퍼 함수들

❓ 문제 2: 문서와 코드의 불일치

// .eslintrc.json - 문서화 강제
{
  "rules": {
    "jsdoc/require-jsdoc": ["error", {
      "require": {
        "FunctionDeclaration": true,
        "MethodDefinition": true,
        "ClassDeclaration": true,
        "ArrowFunctionExpression": false,
        "FunctionExpression": false
      },
      "publicOnly": true
    }],
    "jsdoc/require-param": "error",
    "jsdoc/require-returns": "error",
    "jsdoc/require-description": "warn"
  }
}

❓ 문제 3: 과도한 문서화

/**
 * 숫자를 1 증가시킵니다.
 * @param n - 증가시킬 숫자
 * @returns 1이 증가된 숫자
 * @example
 * increment(5) // 6을 반환합니다
 */
function increment(n: number): number {
  return n + 1;
}

❓ 문제 4: 다국어 문서 지원

/**
 * Creates a new user account.
 * 새로운 사용자 계정을 생성합니다.
 * 
 * @param userData - User information / 사용자 정보
 * @param userData.email - Email address / 이메일 주소
 * @param userData.name - User name / 사용자 이름
 * @returns Created user object / 생성된 사용자 객체
 * 
 * @example
 * ```typescript
 * const user = await createUser({
 *   email: 'user@example.com',
 *   name: 'John Doe'
 * });
 * ```
 */
async function createUser(userData: CreateUserDto): Promise<User> {
  // Implementation
}

❓ 문제 5: 성능 문서화

/**
 * 배열에서 특정 값을 찾습니다.
 * 
 * @remarks
 * **시간 복잡도**: O(n) - 선형 탐색<br>
 * **공간 복잡도**: O(1) - 추가 메모리 사용 없음
 * 
 * 대량의 데이터에서 빠른 검색이 필요하면
 * {@link binarySearch}를 사용하세요 (O(log n)).
 * 
 * @param array - 검색할 배열
 * @param target - 찾을 값
 * @returns 값의 인덱스, 없으면 -1
 */
function linearSearch<T>(array: T[], target: T): number {
  for (let i = 0; i < array.length; i++) {
    if (array[i] === target) return i;
  }
  return -1;
}

🎁 보너스: 유용한 도구와 리소스

🔌 VS Code 확장 프로그램

📚 학습 리소스

🤖 AI 도구 활용

// GitHub Copilot을 활용한 문서 작성
// 함수 시그니처를 작성하고 /** 를 입력하면
// Copilot이 자동으로 문서를 제안해줘

function processUserData(
  userId: string,
  options: ProcessOptions
): Promise<ProcessResult> {
  // Copilot이 위 시그니처를 보고
  // 적절한 TSDoc 주석을 제안해줘
}

🎨 문서 테마 커스터마이징

// typedoc.json
{
  "theme": "default",
  "customCss": "./docs-theme/custom.css",
  "customJs": "./docs-theme/custom.js",
  "favicon": "./docs-theme/favicon.ico",
  "logo": "./docs-theme/logo.png",
  "hideGenerator": true,
  "footerDate": true
}

📊 문서 분석 도구

# documentation.js - 문서 품질 분석
npm install -g documentation

# 문서 커버리지 리포트 생성
documentation lint src/**/*.ts

# 문서 품질 점수 확인
documentation coverage src/**/*.ts

🎯 마무리하며