[Rust 공식문서 한국어 정리] ⑮. The Rustdoc Book

[Rust 공식문서 한국어 정리] ⑮. Rust 문서화 도구: rustdoc

원문 제목: The Rustdoc Book
작성자: The Rust Project

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 1. 서론 — 이 문서가 다루는 내용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Rust는 코드와 문서를 동시에 작성할 수 있는 강력한 문서화 시스템을 제공합니다.
rustdoc은 이 시스템의 핵심 도구로, 소스 코드 주석으로부터 HTML 문서를 자동 생성합니다.
이 문서에서는 rustdoc의 사용법, 주석 문법, 그리고 고급 설정까지 상세히 다룹니다.
Cargo와의 통합, 크로스 플랫폼 문서 생성, 낭부 동작 원리를 이해하는 데 도움이 됩니다.
rustdoc 하나만으로도 전문적인 API 문서를 만들 수 있다는 점이 Rust의 큰 매력입니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 2. 핵심 개념
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

① 문서 주석(doc comment) — ///와 //!
Rust에서는 ///로 아이템 외부 문서를, //!로 모듈/크레이트 수준 문서를 작성합니다.
Markdown 문법을 지원하며, 코드 예시도 자동으로 테스트됩니다.

② 문서 테스트(doc-test)
rustdoc은 문서 속 코드 블록을 자동으로 추출해 테스트로 실행합니다.
이 덕분에 문서와 실제 코드가 항상 동기화된 상태를 유지할 수 있습니다.

③ Cargo doc 명령어
Cargo는 rustdoc을 래핑해 cargo doc 명령어를 제공합니다.
의존성 크레이트의 문서까지 함께 생성할 수 있어 전체 프로젝트 문서를 한눈에 볼 수 있습니다.

④ 문서 속 링크와 교차 참조
Rustdoc은 [ModuleName] 같은 문법으로 타입과 모듈 간 자동 링크를 생성합니다.
이 기능은 대규모 프로젝트에서 API 탐색을 획기적으로 개선합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 3. 주요 내용 상세
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

rustdoc은 단순히 주석을 HTML로 변환하는 것 이상의 기능을 제공합니다.
먼저 문서 주석은 컴파일러가 아닌 rustdoc에 의해 처리되는 특별한 주석입니다.
/// 로 시작하는 외부 문서는 다음 아이템에, //! 는 상위 아이템(모듈/크레이트)에 적용됩니다.

코드 블록 앞에 ignore, no_run, should_panic 같은 속성을 붙여 테스트 동작을 제어할 수 있습니다.
예를 들어 no_run은 컴파일만 검증하고 실행하지 않으며, ignore는 테스트에서 제외합니다.

rustdoc은 --open 플래그로 생성된 문서를 브라우저에서 바로 열 수 있게 합니다.
또한 --document-private-items 옵션으로 비공개 아이템까지 문서에 포함시킬 수 있습니다.

고급 사용자를 위해 rustdoc은 플러그인 시스템과 테마 커스터마이징을 지원합니다.
HTML 템플릿을 오버라이드하거나, CSS를 추가해서 팀/회사의 브랜드에 맞게 문서를 꾸밀 수 있습니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 4. 실전 활용 / 예시
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

새 Rust 프로젝트를 시작할 때 cargo doc --open 하나만으로 전체 API 문서를 즉시 확인할 수 있습니다.
라이브러리 크레이트를 배포하기 전에 반드시 문서 테스트를 실행해 깨진 예제가 없는지 확인하세요.
비공개 모듈의 문서가 필요하면 cargo doc --document-private-items를 사용하면 됩니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 5. 정리
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

rustdoc은 Rust 생태계의 문서 품질을 높이는 핵심 도구입니다.
주석 기반 문서화와 자동 테스트가 결합되어 있어 유지보수 부담을 크게 줄여줍니다.
모든 Rust 개발자는 rustdoc의 기본 기능을 숙지하고 프로젝트에 적극 활용해야 합니다.

📎 출처 링크
https://doc.rust-lang.org/rustdoc/

#Rust #Rustlang #rustdoc #문서화 #공식문서