typescript-docs은(는) 무엇을 하나요?
JSDoc, TypeDoc, 그리고 다양한 계층의 문서화 패턴을 활용하여 TypeScript 프로젝트의 포괄적인 문서를 생성합니다. API 문서, 아키텍처 결정 기록(ADR), 코드 예제, NestJS, Express, React, Angular, Vue와 같은 프레임워크별 패턴을 만들 때 사용하세요.
주요 기능
- 자동 API 문서 생성: JSDoc 주석과 TypeDoc을 기반으로 타입, 함수, 클래스, 인터페이스에 대한 상세 문서를 자동 생성합니다.
- 다계층 문서화: 초보자, 팀원, 아키텍트 등 다양한 대상 독자에 맞춰 문서의 깊이와 초점을 조절할 수 있습니다.
- 아키텍처 결정 기록(ADR): 프로젝트의 주요 설계 결정과 그 이유를 체계적으로 기록할 수 있는 템플릿을 제공합니다.
- 프레임워크별 패턴: NestJS, Express, React, Angular, Vue 등 각 프레임워크에 특화된 문서화 패턴과 예제를 제공합니다.
사용 방법
- 프로젝트에 JSDoc 및 TypeDoc을 설정합니다.
- 코드에 JSDoc 주석을 추가합니다 (함수, 클래스, 인터페이스, 타입 등).
npx typedoc명령어로 문서를 생성합니다.- ADR이 필요한 경우
docs/adr/디렉토리에 마크다운 파일을 생성합니다. - 프레임워크별 패턴에 따라 사용 예제와 가이드를 작성합니다.
JSDoc 주석 예제
/**
* 사용자 프로필을 나타냅니다.
*
* @remarks
* 이 인터페이스는 사용자 인증 및 프로필 관리 시스템에서 사용됩니다.
*
* @example
* ```typescript
* const user: UserProfile = {
* id: '123',
* name: '홍길동',
* email: 'hong@example.com'
* };
* ```
*/
export interface UserProfile {
/** 사용자의 고유 식별자 */
id: string;
/** 사용자의 전체 이름 */
name: string;
/** 사용자의 이메일 주소 */
email: string;
}
다계층 문서화 구조
- Level 1: 빠른 시작 가이드 - 프로젝트를 처음 접하는 개발자를 위한 간단한 사용법
- Level 2: 상세 API 문서 - 모든 함수, 클래스, 타입의 전체 시그니처와 설명
- Level 3: 아키텍처 개요 및 의사 결정 - 프로젝트의 설계 철학과 주요 결정 사항
아키텍처 결정 기록 (ADR) 템플릿
# ADR-[번호]: [결정 제목]
## 상태
- [제안됨 / 승인됨 / 폐기됨 / 대체됨]
## 컨텍스트
- 여기에 결정이 필요한 상황과 배경을 설명합니다.
## 결정
- 여기에 내린 결정의 세부 사항을 설명합니다.
## 결과
- 이 결정의 긍정적, 부정적 영향과 추적해야 할 사항을 설명합니다.
지원 프레임워크
| 프레임워크 | 문서화 패턴 | 예제 위치 |
|---|---|---|
| NestJS | 모듈, 컨트롤러, 서비스, 가드, 파이프 | docs/frameworks/nestjs/ |
| Express | 라우트 핸들러, 미들웨어, 오류 처리 | docs/frameworks/express/ |
| React | 컴포넌트, 훅, 컨텍스트, 프로퍼티 | docs/frameworks/react/ |
| Angular | 모듈, 컴포넌트, 서비스, 디렉티브, 파이프 | docs/frameworks/angular/ |
| Vue | 컴포넌트, 컴포저블, 플러그인, 디렉티브 | docs/frameworks/vue/ |
권장 폴더 구조
project-root/
├── src/
│ ├── components/ # React/Angular/Vue 컴포넌트
│ ├── modules/ # NestJS 모듈
│ ├── routes/ # Express 라우트
│ ├── services/ # 비즈니스 로직
│ └── utils/ # 유틸리티 함수
├── docs/
│ ├── adr/ # 아키텍처 결정 기록
│ ├── frameworks/ # 프레임워크별 문서
│ └── api/ # TypeDoc 생성 API 문서
└── typedoc.json
TypeDoc 설정 예제
{
"entryPoints": ["src/index.ts"],
"out": "docs/api",
"includeVersion": true,
"hideGenerator": true,
"theme": "default",
"excludePrivate": true,
"excludeProtected": false,
"excludeExternals": true
}