19.1 Documentation
문서 주석은 대형 프로젝트에서 문서화를 요구할 때 매우 유용하다. Rustdoc, 을 실행하면, 주석들을 컴파일 하며 문서로 만든다. 이들은 ///로 표시되고, Markdown을 지원한다.
/// person은 여기서 표현됩니다.
pub struct Person {
/// person은 반드시 이름이 있어야 한다, 줄리엣이 싫어하건 말건
name: String,
}
impl Person {
/// 그들이 준 이름을 가진 person을 반환
///
/// # 인자들
///
/// * `name` - person이 소지하는 string 조각
///
/// # 예제
///
/// ```
/// // 당신은 rust 코드를 주석 범위 내부에 넣을 수 있다.
/// // 만약 당신이 --test를 Rustdoc에게 인자로 주면, 당신을 위해 테스트까지 해줄 것이다!
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person {
name: name.to_string(),
}
}
/// 친근하게 인사를 하자!
///
/// `Person`의 이름대로 "Hello, [name]"라고 말하기.
pub fn hello(& self) {
println!("Hello, {}!", self.name);
}
}
fn main() {
let john = Person::new("John");
john.hello();
}테스트를 실행하려면, 먼저 코드를 라이브러리로 빌드한 다음 rustdoc에 라이브러리를 찾을 위치를 지정하여 각 doctest 프로그램에 연결할 수 있도록 해야 한다.
rustc doc.rs --crate-type lib
rustdoc --test --extern doc="libdoc.rs"
(cargo test를 라이브러리 crate에서 실행하면, 카고는 자동으로 알맞는 rustc와 rustdoc 명령어를 생성하고 실행할 것이다.)