{{tag>[cli rust rustdoc documentation doctest]}}

====== rustdoc / cargo doc ======
Rust API HTML documentation을 생성하고 documentation example을 test하는 official documentation tool.

===== Summary =====
Cargo project에서는 dependency와 feature를 함께 처리하는 ''cargo doc''을 우선 사용하고, 단일 crate 또는 Markdown rendering을 직접 제어할 때 ''rustdoc''을 사용한다.

===== Installation =====
''rustdoc''은 rustup toolchain에 포함된다. local HTML documentation 묶음이 필요하면 ''rust-docs'' component를 추가한다.

<code bash>
rustup default stable
rustup component add rust-docs
rustdoc --version
</code>

===== Usage =====
<code bash>
cargo doc [options]
rustdoc [options] input
</code>

  * ''<color #c3c3c3>**cargo**</color> <color #ff7f27>doc</color> <color #22b14c>[options...]</color>''
  * ''<color #c3c3c3>**rustdoc**</color> <color #22b14c>[options...]</color> <color #7092be>INPUT</color>''

===== Options =====
  * ''cargo doc --no-deps'': dependency documentation 생성을 생략.
  * ''cargo doc --document-private-items'': private item 포함.
  * ''cargo doc --open'': 생성 후 browser로 열기.
  * ''rustdoc -o DIR'': output directory 지정.
  * ''rustdoc --crate-name NAME'': crate 이름 지정.
  * ''rustdoc --document-private-items'': private item 포함.
  * ''rustdoc --test INPUT'': documentation code example 실행.
  * ''rustdoc --target TRIPLE'': 다른 target용 documentation 생성.
  * ''rustdoc --edition YEAR'': source와 doctest edition 지정.

===== Examples =====
<code bash>
cargo doc --no-deps
cargo doc --workspace --all-features
cargo doc --document-private-items
cargo test --doc
rustdoc src/lib.rs -o target/doc
rustdoc --test src/lib.rs
</code>

===== Documentation Tests =====
public API example은 compile 가능한 최소 example로 유지한다. network, wall-clock, external service에 의존하는 doctest는 deterministic test로 바꾸거나 적절한 annotation과 이유를 문서화한다.

===== Safety =====
  * ''cargo doc --open''과 ''rustup doc''은 GUI/browser를 열 수 있으므로 headless server와 CI에서는 사용하지 않는다.
  * custom HTML header, CSS, theme file은 generated documentation에 포함되므로 신뢰할 수 있는 repository content만 사용한다.

===== Troubleshooting =====
  * private 또는 feature-gated API가 보이지 않으면 ''--document-private-items''와 Cargo feature selection을 확인한다.
  * doctest failure는 hidden line, working directory, edition, target-specific code 차이를 확인한다.
  * cross target 문서화는 해당 standard library component와 cfg 조건이 필요할 수 있다.

===== Help =====
+++ rustdoc --help |
<code text>
로컬 실행 파일이 없어 live output을 수집하지 않았다.
rustdoc --help
cargo doc --help
</code>
+++

===== See Also =====
  * [[rust:ko]]
  * [[rust:cargo:ko]]
  * [[rust:rustc:ko]]
  * [[https://doc.rust-lang.org/rustdoc/|The rustdoc book]]

===== History =====
  * codex:: 2026-07-20 Added rustdoc and cargo doc generation, doctest, safety, and troubleshooting reference.

{{indexmenu>.#1|js}}