TypeScript 주석

1. 문서 주석의 필요성
2. TSDoc을 사용하여 TypeScript에서 API 문서 생성

이 문서는 TypeScript의 문서 주석에 관한 것입니다.

문서 주석의 필요성

문서 주석은 대부분의 프로그래밍 언어에서 볼 수 있습니다. 주요 목적은 주어진 코드베이스에 대한 문서를 생성하는 것입니다.

JavaDoc을 사용하여 Java로 문서를 생성하고 JSDoc은 JavaScript용 API 문서 생성기입니다. TypeScript는 TSDoc을 사용하여 API 문서를 생성합니다.

TSDoc을 사용하여 TypeScript에서 API 문서 생성

TSDoc은 프로그래머에게 코드베이스에 주석을 다는 방법을 알려주는 사양입니다. 도구가 API 문서를 생성하고 TypeScript 코드베이스에 대한 메타데이터를 생성할 수 있도록 합니다.

Microsoft TypeScript 팀은 TSDoc 사양을 유지 관리합니다. JSDoc에서 유형을 명시적으로 지정하려면 주석을 사용해야 합니다.

TypeScript는 유형이 지정된 언어이므로 TSDoc에서 주석을 사용할 필요가 없으며 번거로움 없이 보다 유익한 문서를 생성하는 데 도움이 됩니다.

TSDoc 주석은 다음과 같이 두 개의 별표로 시작합니다.

/**
*
*
*/

또한 다음과 같이 매개변수, 반환 유형 등과 같은 특수 정보를 지정하기 위해 @ 주석 표시를 제공합니다.

export class Square {
    /**
     * @Returns the area of the given square.
     *
     * @param width  - width of the square
     * @param height - the height of the square
     * @returns The multiplication of `width` and `height`.
     */
    static calculateArea(width: number, height: number): number {
      return width * height;
    }
  }

Visual Studio Code를 사용하여 API 문서 생성

문서 주석은 두 개의 별표로 시작하여 계속됩니다. @Returns, @param 주석은 코드베이스에 대한 추가 정보를 제공했습니다.

Visual Studio Code를 사용하여 calculateArea 함수에 대해 생성된 API 문서를 볼 수 있습니다.

TypeDoc을 사용하여 TSDoc 주석을 HTML 문서로 변환

TSDoc 주석을 사용하여 HTML 문서도 생성할 수 있습니다. 그런 다음 TypeDoc 유틸리티 도구를 사용하여 TSDoc 주석을 렌더링된 HTML 문서로 변환해야 합니다.

먼저 아래와 같이 typedoc를 설치해야 합니다.

npm install --save-dev typedoc

그런 다음 typedoc 명령줄 유틸리티를 사용하여 HTML 문서를 쉽게 생성할 수 있습니다.

typedoc --out docs .

다른 도구는 TypeScript 코드에서 TSDoc 주석을 사용하고 이를 구문 분석하여 API 문서, HTML 문서 및 코드베이스에 관한 기타 유용한 정보를 생성할 수 있습니다.