#48 API 주석에 TSDoc 사용하기

이펙티브 타입스크립트 (댄 밴더캄 지음) 를 읽고 정리

📍요약

✅JSDoc / TSDoc 형태의 주석을 작성하면 에디터에서 주석 정보를 제공해준다

✅@params, @returns 구문과 문서 서식을 위해 마크다운을 사용할 수 있다

✅주석에 타입 정보를 포함하면 안된다 => 코드를 봐야할지, 주석을 봐야할지 혼란 초래

📍JSDoc / TSDoc 의 장점

✅대부분의 에디터에서 함수에 붙은 JSDoc 스타일의 주석을 툴팁으로 표시해 준다

- 함수 설명을 툴팁으로 표시

/** Generate a greeting. Result is formatted for display. */
function greetJSDoc(name: string, title: string) {
  return `Hello ${title} ${name}`;
}

- 매개변수와 반환값을 툴팁으로 표시

/**
 * Generate a greeting.
 * @param name Name of the person to greet
 * @param title The person's title
 * @returns A greeting formatted for human consumption.
 */
function greetFullTSDoc(name: string, title: string) {
  return `Hello ${title} ${name}`;
}

- 타입 설명을 툴팁으로 표시

interface Vector3D {}
/** A measurement performed at a time and place. */
interface Measurement {
  /** Where was the measurement made? */
  position: Vector3D;
  /** When was the measurement made? In seconds since epoch. */
  time: number;
  /** Observed momentum */
  momentum: Vector3D;
}

- JSDoc / TSDoc 은 마크다운 문법을 사용할 수 있다

/**
 * ## This _interface_ has **three** properties:
 * - x
 * - y
 * - z
 */
interface Vector3D {
  x: number;
  y: number;
  z: number;
}

⭐JSDoc 에서는 @params 나 @returns 로 타입 정보를 표시해도 되지만,

타입스크립트에서는 타입 정보가 이미 코드 내에 있기 때문에 TSDoc 에 타입 정보를 표시하면 안된다

- 실수로 코드와 주석이 다른 경우 혼란을 초래할 수 있다

📍요약

📍JSDoc / TSDoc 의 장점

티스토리툴바