suyeonme

[Typescript] TSDoc이란? 본문

프로그래밍👩🏻‍💻/Typescript

[Typescript] TSDoc이란?

suyeonme 2022. 6. 1. 15:10

1. TSDoc이란?

TSDoc은 타입스크립트 코드에서 사용되는 doc comments로 , API 문서를 작성하고 코드에 대한 메타 데이터를 정의할 수 있다. 타입스크립트는 정적 타이핑을 제공하기 때문에 TSDoc을 사용하면 코드에 대한 디테일을 수월하게 기술할 수 있다. 

 

VScode에서 TSDoc 을 지원하므로 TSDoc의 태그를 사용하여 커멘트를 남기면, 하이라이팅이 되어 손쉽게 커멘트를 식별할 수 있으며 코드에 대한 힌트를 얻을 수 있다는 장점이 있다. 

TSDoc 예시

 

규칙은 아래와 같다.

  • 커멘트는 /**로 시작한다.
  • 태그는 @를 사용한다. (e.g. @returns)

 

2. 태그(Tag) 종류

태그를 사용하여 커멘트의 사용 용도를 분류할 수 있다. 자주사용할 것 같은 태그를 정리하였다.

 

@deprecated 

더이상 유지 보수되지 않는 API등에 대해서 사용한다.

/**
 * @deprecated Use the new {@link Control} base class instead.
 */
 const getMembers = async () => await axios.get('get/members');

@defaultValue

class, interface의 field나 property의 값이 명시되어있지 않은 경우, 해당 field, property의 default value를 나타낼 때 사용한다.

enum ViewType {
  Drawer = 'Drawer',
  Modal = 'Modal',
  Text = 'Text'
};

interface MemberForm {
  /**
   * @defaultValue
   * ViewType.Modal
  */
  viewType?: ViewType;
}

@example

함수등에 대한 예시 및 사용법을 정의하는데 사용한다.

/**
 * Adds two numbers together.
 * @example
 * Here's a simple example:
 * ```
 * // Prints "2":
 * console.log(add(1,1));
 * ```
 * @example
 * Here's an example with negative numbers:
 * ```
 * // Prints "0":
 * console.log(add(1,-1));
 * ```
 */
export const add = (x: number, y: number): number => {//...}

@experimental, @beta, @alpha, @public

소프트웨어 life cycle은 크게 alpha - beta - public(stable) release로 구성된다. 각 사이클별 특징은 아래와 같다.

 

1. alpha:  개발 사이클의 가장 첫 단계로 주로 테스트(white-box, black-box등)가 이루어지며 기능이 매우 불안정하다.

2. beta: alpha 다음 단계로 기능 개발은 완료되었으나 아직 발견되지 않은 버그가 있을 수 있다. 

3. stable: 테스트가 완료되고 기능이 안정화된 상태이다.

 

 각 사이클별로 사용하는 태그는 아래와 같다.

  • @alpha: 릴리즈 단계가 alpha인 경우에 사용한다.
  • @beta: 릴리즈 단계가 beta인 경우에 사용한다. 
  • @experimental: @beta와 동일하나 @alpha 릴리즈 단계를 지원하지 않는 경우에 사용한다.
  • @public: 기능이 stable하며 공식 릴리즈로 나가는 경우 사용한다. 

@link

인라인 태그이며, 참조 링크, 혹은 특정 컴포넌트등을 나타내고 싶을 때 사용한다.

/**
 * {@link https://github.com/microsoft/tsdoc}
 * {@link Button}
 * {@link my-control-library#Button | the Button class}
 */

@override, @virtual

함수의 property가 오버라이딩 되는 경우 사용한다. 이 때 base가 되는 클래스는 @virtual을 사용한다.

class Base {
  /** @virtual */
  public render(): void {}
}

class Child extends Base {
  /** @override */
  public render(): void;
}

@param, @returns

  • @param: 함수의 파라미터를 나타낼 때 사용한다.
  • @returns: 함수의 리턴값에 대해 나타낼 때 사용한다.
/**
 * @description Returns the average of two numbers.
 * @param x - The first input number
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 *
 */
const getAverage = (x: number, y: number): number => (x + y) / 2.0;

@readonly

특정 함수나 값등이 readonly임을 명시할 때 사용한다.

class Book {
  /**
   * @readonly
   */
  public get title(): string {
    return this._title;
  }

  public set title(value: string) {
    throw new Error('This property is read-only!');
  }
}

@remarks, @description, @summary

모두 비슷한 용도로 사용된다. 

  • @summary: 요약
  • @remarks: 요약에 대한 디테일
  • @description: 설명

@see

레퍼런스나 다른 참고할 리소스를 나타낼 때 사용한다.

/**
 * @see {@link ParsedUrl} for the returned data structure
 * @see {@link https://tools.ietf.org/html/rfc1738|RFC 1738}
 * @see Component.tsx
 */
function parseURL(url: string): ParsedUrl;
Comments