Item 48 API 주석에 TSDoc 사용하기

JSDoc, TSDoc

다음과 같이 JSDoc을 작성할 수 있다.

/** 인사말을 생성한다. 결과는 보기 좋게 꾸며진다. */
funciton greetJSDoc(name: string, title: string) {
  return `Hello ${title} ${name}`
}

대부분의 편집기는 인라인 주석(//)과 달리 JSDoc은 마우스를 올리면 툴팁으로 표시해준다.

만약 공개 API에 주석을 붙인다면 JSDoc 형태로 작성해야 한다. @param, @returns와 같은 일반적 규칙을 사용할 수 있다. 타입스크립트 관점에서는 TSDoc이라고 부르기도 한다.

TSDoc 주석은 마크다운 형식으로 꾸며지므로, 굵은 글씨, 기울임 등 다양하게 꾸밀 수 있다.

주석은 간단히 요점만 언급하고, 타입 정보는 코드에 있으니 타입 정보를 TSDoc에 넣지 말자.(Item 30)

Summary

• 익스포트된 함수, 클래스, 타입에 주석을 달 때는 JSDoc/TSDoc 형태를 사용하자. 편집기가 주석 정보를 표시해 준다.

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

• 주석에 타입 정보를 표시하지 말자.(Item 30)