문서

English.

문서 집합

위치	내용
README.md	프로젝트 소개, 최소 시작 절차, 문서 링크
AGENTS.md	개발 규칙과 필수 검사
docs/spec/	승인된 계약: 규칙, 구조, 인수 기준
docs/features.md	근거 링크를 포함한 기능별 구현, 검증, 배포
docs/operations/	개발, 적합성, 브라우저 테스트, 발행, 문서의 현재 절차
docs/plans/	승인 대기 제안. 승인 후 내용을 명세로 옮기고 제안을 제거한다
CHANGELOG.md	실제 변경과 검증 결과

모든 문서는 같은 정보를 가진 .ko.md 파일을 가진다.

규칙

• docs/spec/의 규칙은 LEX-1과 같은 식별자를 가진다. 픽스처와 테스트는 식별자를 인용한다.
• 문서는 현재 동작을 서술한다. 명세되었지만 구현되지 않은 부분은 명세와 docs/features.md에 그렇게 표시한다.
• 기능 행은 구현에 not-started, in-progress, implemented, 검증에 pending, passed, failed, 배포에 not-deployed, deployed 값과 근거로 상대 링크를 사용한다.
• 코드 블록은 영어 파일과 한글 파일에서 같다.
• 쌍의 두 파일은 같은 <!-- doc-id: <id> -->를 한 번 가지고, 한글 파일은 <!-- source-sha256: <영어 파일의 sha256> -->를 한 번 가지며, 이 값은 번역을 검토한 뒤에 갱신한다.

검사기

make documents-check

검사기는 문서에 번역 쌍이 없거나, 상대 링크가 해석되지 않거나, 링크가 절대 경로이거나, 두 언어의 코드 블록이 다르거나, 기능 행의 상태가 유효하지 않거나 근거 링크가 없거나, checklist docs/plans/execution-checklist.md의 작업 행 상태가 유효하지 않거나 두 언어 사이에 다르거나, checklist에 heading(제목 포함)이나 작업 표 행이 아닌 줄이 있거나, 상태 표시나 task list 표시가 작업 행 마지막 칸의 시작이 아닌 곳에 있으면 실패하고, 그런 줄과 표시는 file, 줄, 열과 함께 보고한다. make docs-check가 검사기를 실행한다.

소스 주석

패키지의 공개 진입 표면에 속한 심볼은 문서 주석을 가진다. 공개 진입 표면은 설치한 패키지가 문서화된 진입점으로 노출하는 것이다:

패키지	공개 진입 표면
packages/ts	src/index.ts, src/render.ts, src/node/index.ts가 다시 내보내는 심볼과 그중 클래스의 공개 멤버
packages/go	모듈 루트 패키지의 공개 식별자, 그 선언이 지칭하는 하위 패키지 타입, 그 타입의 공개 메서드
packages/php	패키지 README의 API 표에 있는 클래스와 그 공개 메서드
packages/rust	모든 공개 항목. 크레이트 속성 #![deny(missing_docs)]이 컴파일러로 검사한다

같은 패키지의 다른 파일이 쓰도록 내보내기만 한 심볼은 내부용이며 문서 주석을 갖지 않는다. 모든 소스 파일은 그 파일이 무엇을 구현하는지 밝히는 주석으로 시작한다. Go 패키지는 그 주석을 패키지의 파일 하나에 둔다.

주석은 그 심볼이 무엇을 위한 것인지 자기 말로 서술한다. 명세 규칙이 동작을 정의하는 경우 주석은 그 내용을 되풀이하지 않고 AST-3처럼 규칙을 지칭한다.

node scripts/check-doc-coverage.mts

검사기는 문서화되지 않은 심볼이나 파일마다 한 행을 보고하고 실패한다. make docs-check가 이를 실행한다.

make docs-static-check는 site를 빌드하고, 페이지가 .ko.md file 같은 source 전용 경로나 이전 경로를 link하거나 자기 locale을 벗어나면 실패한다. docs/ 아래 한국어 문서는 다른 한국어 페이지를 site route /ko/<path>로 link한다. make owner-check는 docs/ 아래 변경에 대해 make docs-check와 함께 이를 실행한다.