Rust API HTML documentation을 생성하고 documentation example을 test하는 official documentation tool.
Cargo project에서는 dependency와 feature를 함께 처리하는 cargo doc을 우선 사용하고, 단일 crate 또는 Markdown rendering을 직접 제어할 때 rustdoc을 사용한다.
rustdoc은 rustup toolchain에 포함된다. local HTML documentation 묶음이 필요하면 rust-docs component를 추가한다.
rustup default stable
rustup component add rust-docs
rustdoc --version
cargo doc [options] rustdoc [options] input
cargo doc [options…]rustdoc [options…] INPUTcargo 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 지정.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
public API example은 compile 가능한 최소 example로 유지한다. network, wall-clock, external service에 의존하는 doctest는 deterministic test로 바꾸거나 적절한 annotation과 이유를 문서화한다.
cargo doc –open과 rustup doc은 GUI/browser를 열 수 있으므로 headless server와 CI에서는 사용하지 않는다.–document-private-items와 Cargo feature selection을 확인한다.