핵심 개념

Docflow는 JSDoc을 기반으로 라이브러리 문서를 자동으로 생성하는 도구예요. JSDoc은 JavaScript 코드에 주석으로 문서화 정보를 작성하는 표준 방식이에요. 이 문서에서는 Docflow의 핵심 개념과 기능을 소개할게요.

한 눈에 보는 흐름도

concept-flow

레퍼런스 문서

Docflow는 JSDoc에서 레퍼런스 문서를 생성합니다.

레퍼런스 문서란?

레퍼런스 문서는 개발자가 특정 API나 함수에 대한 정확하고 완전한 정보를 빠르게 찾을 수 있도록 설계된 문서예요.

Mozilla의 Web API 문서나 Node.js API 문서처럼, 개발자가 "이 함수는 어떻게 사용하지?", "매개변수는 무엇을 받지?", "반환값은 뭐지?" 같은 질문의 답을 즉시 찾을 수 있어야 합니다.

Docflow는 JSDoc의 @param, @returns, @example 같은 태그를 분석해서 함수 시그니처, 매개변수 테이블, 반환값 설명, 실제 사용 예제를 포함한 완전한 레퍼런스 문서를 자동으로 생성해요.

JSDoc 지원 태그

Docflow는 JSDoc의 표준 태그와 문서 생성을 위한 커스텀 태그를 지원해요. 각 태그는 특정 목적에 따라 사용되며, 문서 생성 과정에서 다양한 역할을 수행해요.

표준 JSDoc 태그: @param, @returns, @throws, @example, @deprecated, @see, @version, @description, @kind, @name

Docflow 전용 태그: @public, @category, @generate

이러한 태그들을 조합해서 구조화된 문서를 자동으로 생성할 수 있어요.

`@public` 태그

@public 태그는 문서화할 대상을 공개 API로 표시해요.

typescript

/**
 * @public
 * ... 다른 JSDoc 설명 ...
 */
export function getUser(id: string): User {
  // ...
}

docflow build 실행 시: @public 태그가 있는 export만 선택해서 문서로 생성해요.
docflow check 실행 시: public API로 export되었지만 @public 태그가 없는 함수나 클래스를 찾아서 알려줘요.

`@generate` 태그

@generate 태그는 AI를 통해 JSDoc을 자동으로 생성할 대상을 표시해요.

typescript

/**
 * @generate
 */
export function calculateTotalPrice(
  items: CartItem[],
  discountRate: number
): number {
  // ...
}

docflow generate 실행 시: 함수 시그니처와 컨텍스트를 LLM에 전달해서 완전한 JSDoc 주석을 자동으로 생성하고 코드에 적용해요.

JSDoc 템플릿 사용법

Docflow는 일관된 문서 생성을 위해 표준화된 JSDoc 템플릿을 사용해요. 다음은 예시 코드에서 사용하는 예시와 생성되는 문서 예시에요.

태그 예시

typescript

/**
 * @public
 * @kind function
 * @category Math
 * @name calculateArea
 * @signature
 * ```typescript
 * calculateArea(radius: number): number
 * ```
 * @description
 * 원의 넓이를 계산합니다. 반지름을 입력받아 파이(π)와 제곱을 이용해 정확한 넓이를 반환합니다.
 *
 * @param {number} radius - 원의 반지름 (양수여야 함)
 * @returns {number} 계산된 원의 넓이
 *
 * @example
 * ```typescript
 * import { calculateArea } from '@mylib/math';
 *
 * const area = calculateArea(5);
 * console.log(area); // 78.53981633974483
 * ```
 *
 * @version Android/5.186.0, iOS/5.231.0, Web/5.0.0
 */
export function calculateArea(radius: number): number {
  return Math.PI * radius * radius;
}

문서 변환 결과

생성되는 파일 경로

docs/references/math/calculateArea.md

Markdown 결과

markdown

---
source: packages/math/src/calculateArea.ts
---

# calculateArea

```typescript
calculateArea(radius: number): number
```

원의 넓이를 계산합니다. 반지름을 입력받아 파이(π)와 제곱을 이용해 정확한 넓이를 반환합니다.

## 매개변수

| 이름   | 타입   | 설명                      |
| ------ | ------ | ------------------------- |
| radius | number | 원의 반지름 (양수여야 함) |

## 반환값

| 타입   | 설명             |
| ------ | ---------------- |
| number | 계산된 원의 넓이 |

## 예제

```typescript
import { calculateArea } from "@mylib/math";

const area = calculateArea(5);
console.log(area); // 78.53981633974483
```

## 버전 정보

- Android: 5.186.0
- iOS: 5.231.0
- Web: 5.0.0

브라우저에서는 이미지와 같이 볼 수 있어요. markdown-example

파일 구조 결정

JSDoc 태그에 따라 파일이 어떻게 구성되는지 알아볼게요.

결정 규칙:

@name 태그 → 파일명 (없으면 함수명 사용)
폴더명 결정 우선순위:
- @category 태그 값 (최우선)
- 자동 감지된 TypeScript 선언 타입 (function, class, interface, type, enum, variable)
- "misc" (기본값)

동작 예시

typescript

// @category 태그 사용 (최우선)
/** @public @category Math */
export function add(a: number, b: number): number {}
// 결과: Math/add.md

// 자동 감지 (TypeScript 기반)
/** @public */
export function multiply(x: number, y: number): number {}
// 결과: function/multiply.md

/** @public */
export class Calculator {}
// 결과: class/Calculator.md

/** @public */
export interface UserConfig {}
// 결과: interface/UserConfig.md

생성되는 폴더 구조:

docs/references/
├── Math/           ← @category "Math"
├── function/       ← 자동 감지된 kind
├── class/          ← 자동 감지된 kind
├── interface/      ← 자동 감지된 kind
├── type/           ← 자동 감지된 kind
├── enum/           ← 자동 감지된 kind
├── variable/       ← 자동 감지된 kind
└── misc/           ← 기본값

:::note @kind 태그는 표준 JSDoc 태그로 파싱되지만, VitePress 제너레이터에서 폴더 구조 결정에는 현재 사용되지 않아요. 폴더명은 @category 태그와 TypeScript 자동 감지만 사용해요. :::

플러그인 시스템

플러그인 시스템은 Docflow의 기본 기능을 확장하거나 커스터마이징할 때 사용해요. 예를 들어 VitePress 대신 Docusaurus나 Nextra로 문서를 생성하고 싶거나, 생성된 문서의 구조를 조직의 규칙에 맞게 변경하고 싶을 때 유용해요.

제너레이터 플러그인

{
  plugins: [
    {
      name: "custom-generator",
      plugin: () => ({
        hooks: {
          provideGenerator: (name) => {
            if (name === "custom") {
              return new CustomGenerator();
            }
          },
        },
      }),
    },
  ];
}

제너레이터 플러그인으로 다양한 문서 형식을 지원할 수 있어요. 기본 VitePress 외에도 Docusaurus, Nextra 등 원하는 문서 시스템과 연동 가능해요.

매니페스트 변환

{
  hooks: {
    transformManifest: (manifest) => {
      // VitePress 사이드바 형식을 Docusaurus 네비게이션으로 변환
      return manifest.map((item) => ({
        type: "category",
        label: item.text,
        items: item.items?.map((subItem) => ({
          type: "doc",
          id: subItem.link.replace(".md", ""),
        })),
      }));
    };
  }
}

Docflow가 기본적으로 생성하는 VitePress 매니페스트 형식을 다른 문서 시스템에서 사용할 수 있는 형식으로 변환할 수 있어요. 예를 들어 Docusaurus의 sidebars.js 형식이나 Nextra의 _meta.json 형식으로 자동 변환할 수 있어요.

시그니처 분석

Docflow는 AST(Abstract Syntax Tree)를 통해 복잡한 TypeScript 타입도 정확하게 분석해서 문서화할 수 있어요.

복잡한 타입 예시:

typescript

// 입력: 제네릭, 조건부 타입, 유니온 타입 등 복잡한 타입
export function process<T extends BaseType>(
  data: T[],
  options?: ProcessOptions<T>
): Promise<Result<T>>;

Configuration

Generator

Manifest

Parser

Plugin

핵심 개념

한 눈에 보는 흐름도

레퍼런스 문서

JSDoc 지원 태그

`@public` 태그

`@generate` 태그

JSDoc 템플릿 사용법

태그 예시

문서 변환 결과

생성되는 파일 경로

Markdown 결과

파일 구조 결정

플러그인 시스템

제너레이터 플러그인

매니페스트 변환

시그니처 분석

핵심 개념 ​

한 눈에 보는 흐름도 ​

레퍼런스 문서 ​

JSDoc 지원 태그 ​

@public 태그 ​

@generate 태그 ​

JSDoc 템플릿 사용법 ​

태그 예시 ​

문서 변환 결과 ​

생성되는 파일 경로 ​

Markdown 결과 ​

파일 구조 결정 ​

플러그인 시스템 ​

제너레이터 플러그인 ​

매니페스트 변환 ​

시그니처 분석 ​

핵심 개념

한 눈에 보는 흐름도

레퍼런스 문서

JSDoc 지원 태그

`@public` 태그

`@generate` 태그

JSDoc 템플릿 사용법

태그 예시

문서 변환 결과

생성되는 파일 경로

Markdown 결과

파일 구조 결정

플러그인 시스템

제너레이터 플러그인

매니페스트 변환

시그니처 분석