documenting-typescript

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 — 시그니처를 읽으면 알 수 있는 것을 산문으로 반복한 태그. 토큰과 유지보수를 쓰고 정보를 주지 않으며, 시그니처가 바뀌면 제일 먼저 거짓말이 된다.

/**
 * 두 값을 더한다.
 * @param a 첫 번째 숫자   ← echo
 * @param b 두 번째 숫자   ← echo
 * @returns 합             ← 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 찾은 경우
 * ```ts
 * find("hello world", "world"); // 6
 * ```
 *
 * @example 없으면 -1
 * ```ts
 * find("hello world", "foo"); // -1
 * ```
 */

• @example 바로 뒤 한 줄이 제목이다. "기본 사용" 두 개보다 "찾은 경우" / "없으면 -1" 처럼 어떤 분기인지를 적는다.
• 붙여넣어 돌아가는 코드로 쓴다. 필요하면 import 를 포함한다.
• 펜스는 ```ts 로 연다.
• 기대 결과는 주석으로 붙인다. 예제가 무엇을 보여주는지가 코드 옆에 있어야 한다.

4. 상태와 링크를 붙인다

• @deprecated — 대체 경로를 함께 적는다. "대신 {@link fetchUser} 를 쓴다."
• @throws — 던지는 조건. 타입이 표현하지 못하는 유일한 실패 경로다.
• @defaultValue — 옵셔널 프로퍼티의 기본값.
• @see — 외부 스펙·이슈·RFC.
• {@link Symbol} — TypeScript 4.3+ 에디터에서 클릭 가능한 링크로 렌더된다. 같은 패키지의 다른 심볼은 이름만 적지 말고 링크로 건다.

5. 첫 문단만 늘어놓고 읽는다

다 쓴 뒤, 손댄 심볼들의 첫 문단만 이름 없이 한 줄씩 나열해 읽는다. 어느 것이 어느 심볼인지 맞지 않는 줄이 호버가 실패한 지점이다. 자동완성 목록이 사용자에게 보여주는 게 정확히 이 화면이다.

문서가 낡았을 때

누락된 문서보다 조용히 거짓이 된 문서가 비싸다. 시그니처를 바꿀 때 JSDoc 을 같은 커밋에서 함께 고친다.

이미 갈라진 걸 찾을 때는 JSDoc 블록의 마지막 수정 커밋과 시그니처 줄의 마지막 수정 커밋을 비교한다 (git log -L '<시작>,<끝>:<파일>'). 시그니처가 더 최근이면 후보다 — 자동 판정이 아니라 읽어서 확인한다. 리팩터링 커밋은 시그니처 줄을 건드리고도 의미를 안 바꾼다.