| name | documenting-typescript |
| description | TypeScript 심볼에 JSDoc을 쓰거나 고친다. 새 export를 추가할 때, public 시그니처를 바꿀 때, 문서 누락·낡음이 지적될 때 사용한다. |
TS 프로젝트에서 JSDoc이 실제로 읽히는 곳은 세 군데다. 호버(에디터 툴팁·자동완성 목록), 에이전트(코드를 읽는 모델이 심볼을 고를 때), 생성 문서(TypeDoc·api-extractor). 셋 다 첫 문단을 가장 크게 취급하고, 나머지는 이미 그 심볼을 고른 사람만 읽는다.
그래서 순서가 정해진다 — 호버를 먼저 확정하고, 시그니처가 못 말하는 것만 뒤에 붙이고, 나머지는 지운다.
심볼 종류별 형태(함수·옵션 객체·클래스·React 컴포넌트·훅·모듈 진입점)는 PATTERNS.md.
1. 호버를 쓴다
첫 문단이 호버다. 자동완성 목록에서 잘려 보이는 것도, 에이전트가 후보 중에 이 심볼을 고를 때 읽는 것도 이 한 문단이다.
- 한 문장. 3인칭 동사로 시작해 결과를 말한다.
- 구현 서술은 두 번째 문단 이후로 내린다.
이름을 다시 읽어주는 문장은 정보가 0이다. 이름이 못 말하는 것을 말한다.
export function getUser(id: string): Promise<User>;
export function getUser(id: string): Promise<User>;
판단 기준: 이름을 가리고 이 문장만 읽었을 때 어떤 심볼인지 짚을 수 있는가.
2. 시그니처가 못 말하는 것만 붙인다
TS에서 타입은 시그니처가 소유한다. @param {string} value 같은 타입 어노테이션은 컴파일러가 무시하고, 시그니처와 갈라진 뒤에도 아무도 잡아주지 않는다.
echo — 시그니처를 읽으면 알 수 있는 것을 산문으로 반복한 태그. 토큰과 유지보수를 쓰고 정보를 주지 않으며, 시그니처가 바뀌면 제일 먼저 거짓말이 된다.
export function sum(a: number, b: number): number;
@param / @returns 는 아래 중 하나를 말할 때 남긴다:
| 축 | 예 |
|---|
| 단위·기준 | ms 인가 s 인가, 0-based 인가 1-based 인가, UTC 인가 로컬인가 |
| 유효 범위 | 벗어난 값에서 벌어지는 일까지 함께 |
| 소유권·수명 | 호출자가 해제하는가, 내부에서 보관하는가, 전달한 객체를 변형하는가 |
| 실패 표현 | -1 / null / throw 중 무엇인가 |
| 부작용 | 네트워크를 치는가, 저장소를 건드리는가, 리렌더를 유발하는가 |
@param 이름은 파라미터 이름과 정확히 일치시킨다. 남길 게 하나도 없으면 호버 한 문단짜리 블록이 정답이다.
3. 분기가 있으면 예제를 쓴다
@example 은 분기당 하나. 성공 경로만 있는 심볼은 예제 없이 끝나도 되고, 실패·옵션·오버로드가 있으면 각각 제목을 단다.
@example 바로 뒤 한 줄이 제목이다. "기본 사용" 두 개보다 "찾은 경우" / "없으면 -1" 처럼 어떤 분기인지를 적는다.- 붙여넣어 돌아가는 코드로 쓴다. 필요하면 import 를 포함한다.
- 펜스는
```ts 로 연다.
- 기대 결과는 주석으로 붙인다. 예제가 무엇을 보여주는지가 코드 옆에 있어야 한다.
4. 상태와 링크를 붙인다
@deprecated — 대체 경로를 함께 적는다. "대신 {@link fetchUser} 를 쓴다."@throws — 던지는 조건. 타입이 표현하지 못하는 유일한 실패 경로다.@defaultValue — 옵셔널 프로퍼티의 기본값.@see — 외부 스펙·이슈·RFC.{@link Symbol} — TypeScript 4.3+ 에디터에서 클릭 가능한 링크로 렌더된다. 같은 패키지의 다른 심볼은 이름만 적지 말고 링크로 건다.
5. 첫 문단만 늘어놓고 읽는다
다 쓴 뒤, 손댄 심볼들의 첫 문단만 이름 없이 한 줄씩 나열해 읽는다. 어느 것이 어느 심볼인지 맞지 않는 줄이 호버가 실패한 지점이다. 자동완성 목록이 사용자에게 보여주는 게 정확히 이 화면이다.
문서가 낡았을 때
누락된 문서보다 조용히 거짓이 된 문서가 비싸다. 시그니처를 바꿀 때 JSDoc 을 같은 커밋에서 함께 고친다.
이미 갈라진 걸 찾을 때는 JSDoc 블록의 마지막 수정 커밋과 시그니처 줄의 마지막 수정 커밋을 비교한다 (git log -L '<시작>,<끝>:<파일>'). 시그니처가 더 최근이면 후보다 — 자동 판정이 아니라 읽어서 확인한다. 리팩터링 커밋은 시그니처 줄을 건드리고도 의미를 안 바꾼다.
