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(): <>;