Typedoc, ts 유틸 함수를 문서화해줘!

1. typedoc의 필요성

• 프로젝트에서 많은 수의 유틸 함수가 있으면, 각 함수의 용도와 사용법을 파악하기 어려워진다.
• 특히 프로젝트가 복잡해지고, 많은 사람들이 참여할 때 문제가 커진다.
• 이러한 문제는 typedoc을 사용해 유틸 함수를 문서화하면 해결할 수 있다!
• typedoc을 사용하면 함수의 용도와 사용법을 명확하게 알 수 있어, 유지 보수가 쉬워지고 개발자들의 생산성을 높일 수 있다 🙂
• 그렇다면 이 typedoc은 무엇이며 어떻게 설정해야할까? 한 번 알아보자!

2. typedoc이란?

1) typedoc은 무엇일까?

• TypeDoc은 TypeScript 코드에서 JSDoc 주석을 추출하여 API 문서로 생성하는 도구이다.
• TypeDoc을 사용하면 TypeScript 코드의 문서화를 쉽게 할 수 있다.
• 아래 코드는 두 숫자의 합을 구하는 함수의 docs 주석 예시이다.

/**
 * 숫자를 더합니다.
 *
 * @alpha
 * @param x - 첫 번째 입력 숫자
 * @param y - 두 번째 입력 숫자
 * @returns x와 y의 합
 *
 * @example
 * ```typescript
 * const result = addNumbers(1, 2);
 * console.log(result); // 3
 * ```
 */
export function addNumbers(x: number, y: number): number {
  return x + y;
}

• docs 변환 파일을 열면 아래와 같이 나타나는데, 페이지에서 함수의 용도와 사용법을 알 수 있다.
  

  

• tsdoc에서 사용할 수 있는 태그는 공식 홈페이지에서 확인할 수 있으므로, 이 링크에서 태그를 확인해보자!

2) typedoc 설정방법

• TypeDoc을 사용하기 위해선 프로젝트에 TypeDoc을 설치하고, 설정 파일을 작성해야 한다.
• TypeDoc 설정은 typedoc.json 파일로 작성할 수 있으며, 필요한 옵션을 추가하여 문서화 방식을 변경할 수 있다.

(1) 프로젝트 설정하기

🎈 우선 프로젝트 셋팅을 해보자! 예시 환경은 yarn으로 진행했다.

• 터미널에 아래 명령어를 입력하여 yarn 기본 환경 설정을 한다.

yarn init

• 그 다음, typescript 셋팅을 한다.

yarn add typescript

• 루트 위치에서 tsconfig.json 파일을 생성하고 typescript 설정 코드를 추가한다.

// ./tsconfig.json

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "esModuleInterop": true,
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "lib": ["es2017"],
    "strict": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

(2) Typedoc 설정하기

🎈 프로젝트 설정도 얼추 했겠다! TypeDoc설정을 해보자~

• 다음 명령어를 사용해 TypeDoc을 설치한다.

yarn add -D typedoc

• 루트 위치에 typedoc.json 파일을 생성하고 TypeDoc 관련 설정 코드를 추가한다.
• 여기서 entryPoints은 문서화할 파일의 경로를 설정하는 옵션이며,
• out은 TypeDoc이 생성한 문서를 저장할 폴더 위치를 뜻한다.

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

• 그럼 위 코드는 문서화할 파일의 경로가 src/index.ts이고, 문서화된 파일이 docs폴더에 저장된다는 뜻이 된다.

• 그 다음 tsconfig.json에 typedoc.json의 설정을 그대로 추가해주자!

  "exclude": ["node_modules"],
  "typedocOptions": {                // this!
    "entryPoints": ["src/index.ts"],
    "out": "docs"
}

• 우리는 entryPoints를 src/index.ts로 했기 때문에, 루트 위치에 src폴더와 src/index.ts를 추가해주자.
• 현재 폴더 구조는 아래와 같다.

• 그리고 잘 작동되는지 확인을 위해 index.ts에 예시코드를 추가했다.

/**
 * 숫자를 더합니다.
 *
 * @alpha
 * @param x - 첫 번째 입력 숫자
 * @param y - 두 번째 입력 숫자
 * @returns x와 y의 합
 *
 * @example
 * ```typescript
 * const result = addNumbers(1, 2);
 * console.log(result); // 3
 * ```
 */
export function addNumbers(x: number, y: number): number {
  return x + y;
} 

• 그 다음 yarn typedoc 명령어를 사용하면…

yarn typedoc

• docs폴더에 변환된 파일이 추가된다!

(3) docs 문서를 여는 2가지 방법

🎈 어 그런데 완성된 문서는 어떻게 확인할 수 있을까? 총 2가지 방법이 있다!

• 첫번째 방법은 index.html을 열어서 확인하는 방법이다.
• 앞서 생성된 docs/index.html을 더블 클릭하면 문서 페이지를 볼 수 있다.

• 혹은 index.html을 열어 확인하기 귀찮다면, 서버를 실행시켜 문서를 볼 수 있다.
• 이를 위해 http-server가 필요한데, http-server는 JavaScript, HTML, CSS 등을 웹서버로 제공하는 도구이다.
• 이 도구를 이용하면 로컬에서 작성한 HTML, CSS, JavaScript 파일을 브라우저에서 실행할 수 있다.
• 아래 명령어를 사용해 http-server를 설치하자!

yarn add http-server 

• 그 다음 package.json에 http-server -o ./docs/index.html 스크립트를 추가해주면 된다.

// package.json
{
  "name": "tsdoc-template",
  "version": "1.0.0",
  ...
  "scripts": {
    "docs": "http-server -o ./docs/index.html"  // this!
  },
  // ...
}제

• 이제 yarn docs를 하면 문서 페이지를 볼 수 있게 된다 🙂

🎈 이번 시간에는 typedoc을 사용해 TypeScript 유틸 함수를 문서화하는 방법을 알아보았다!
typedoc은 JSDoc 주석을 추출하여 API 문서로 생성하는 도구이며, typedoc.json 파일을 작성하여 설정할 수 있었다.

추가적으로 작성한 docs 주석이 어떻게 나타나는지 바로 보고 싶다면,
공식문서의 playground를 확인해보자