문서화
target/doc에 문서를 빌드하려면 cargo doc을 사용하세요. cargo doc --open은 웹 브라우저에서 문서를 자동으로 엽니다.
모든 테스트(문서 테스트 포함)를 실행하려면 cargo test를, 문서 테스트만 실행하려면 cargo test --doc을 사용하세요.
이러한 명령어들은 필요에 따라 rustdoc(및 rustc)을 적절히 호출합니다.
문서 주석
문서 주석은 문서화가 필요한 큰 프로젝트에 매우 유용합니다. rustdoc을 실행할 때, 이 주석들이 문서로 컴파일됩니다. 이들은 ///로 표시되며 Markdown을 지원합니다.
#![crate_name = "doc"]
/// 여기에 사람(human being)이 표현됩니다.
pub struct Person {
/// 줄리엣이 아무리 싫어하더라도 사람은 이름을 가져야 합니다.
name: String,
}
impl Person {
/// 주어진 이름으로 사람을 생성합니다.
///
/// # Examples
///
/// ```
/// // 주석 내부의 울타리(fence) 사이에 Rust 코드를 넣을 수 있습니다.
/// // `rustdoc`에 --test를 전달하면, 코드 테스트까지 해줍니다!
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person {
name: name.to_string(),
}
}
/// 친절하게 인사합니다!
///
/// 호출된 `Person`의 이름을 사용하여 "안녕, [name](Person::name)"이라고 말합니다.
pub fn hello(&self) {
println!("안녕, {}!", self.name);
}
}
fn main() {
let john = Person::new("존");
john.hello();
}테스트를 실행하려면 먼저 코드를 라이브러리로 빌드한 다음, rustdoc이 각 문서 테스트 프로그램에 링크할 수 있도록 라이브러리 위치를 알려주어야 합니다.
$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs
문서 속성
다음은 rustdoc과 함께 사용되는 가장 일반적인 #[doc] 속성의 몇 가지 예입니다.
inline
별도의 페이지로 링크하는 대신 문서를 인라인으로 표시하는 데 사용됩니다.
#[doc(inline)]
pub use bar::Bar;
/// bar 문서
pub mod bar {
/// Bar에 대한 문서
pub struct Bar;
}no_inline
별도의 페이지나 다른 곳으로 링크되는 것을 방지하는 데 사용됩니다.
// libcore/prelude에서 가져온 예시
#[doc(no_inline)]
pub use crate::mem::drop;hidden
이를 사용하면 rustdoc이 해당 항목을 문서에 포함하지 않도록 합니다.
// futures-rs 라이브러리에서 가져온 예시
#[doc(hidden)]
pub use self::async_await::*;문서화를 위해 커뮤니티에서는 rustdoc이 널리 사용됩니다. 표준 라이브러리 문서를 생성하는 데 사용되는 도구이기도 합니다.