[Rust] 주석

유용한 문서화 주석 

슬래시 세개(///)를 이용하여 텍스트 서식을 위한 마크 다운 표기법을 지원합니다. 문서화 주석은 문서화할 대상 바로 이전에 배치하면 됩니다. 

 

Filename: src/lib.rs

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let five = 5;
///
/// assert_eq!(6, my_crate::add_one(5));
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

 

cargo doc --open 을 실행시키면 현재 크레이트의 문서에 대해 (심지어 크레이트가 가진 모든 디펜던시의 문서까지) HTML 을 생성하고 웹 브라우저에 띄워줍니다. 

 

자주 사용되는 구절

- Panics : 문서화된 기능이 패닉을 일으킬 수 있는 시나리오 입니다. 함수를 호출하는 사람들에게 "프로그램이 패닉을 일으키지 않게 하려면 이러한 상황에서는 이 함수를 호출하지 않아야 합니다" 라는 내용을 알려줍니다.

- Error : 해당 함수가 Result를 반환할 경우에는 발생할 수 있는 에러의 종류와 해당 에러들이 발생하는 조건을 설명해 주어서 호출하는 사람이 여러 에러를 여러 방법으로 처리할 수 있도록 합니다.

- safety : 함수가 안전하지 않을(unsafe)의 경우에 왜 이 함수가 안전하지 않은지와 이 함수가 호출하는 사람에게 지키길 기대하는 불변성에 대해 알려주는 구절이 있어야 합니다. 

 

주석을 포함하는 항목을 문서화 하기

문서화 주석의 또 다른 스타일로 //! 가 있습니다. 이는 주석 뒤에 오는 항목을 문서화 하는게 아닌 주석을 포함하는 항목을 문서화 합니다. 일반적으로 크레이트의 루트 파일 (관례적으로 src/lib.rs 입니다) 이나 크레이트 혹은 모듈 전체를 문서화하는 모듈 내부에 이 문서화 주석을 작성합니다.

예시로, 만약 add_one 함수를 포함한 my_crate 크레이트를 설명하기 위한 목적으로 문서화를 진행한다면, src/lib.rs 에 //! 로 시작하는 문서화 주석을 추가할 수 있습니다.

Filename: src/lib.rs

//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
// --snip--

//! 로 시작하는 줄 중 마지막 줄에 코드가 뒤따르지 않는다는 점을 주목하세요. 우린 주석 뒤에 따라오는 항목이 아닌, 주석을 포함하는 항목을 문서화 할 것이기에 /// 가 아니라 //! 로 시작하는 주석을 사용했습니다. 이 경우, 주석을 포함하는 항목은 크레이트의 루트 파일인 src/lib.rs 이며 주석은 전체 크레이트를 설명하게 됩니다.

cargo doc --open 을 실행하면, my_crate 문서 첫 페이지 내용 중 크레이트의 공개 아이템들 상단에 이 주석의 내용이 표시될 것입니다.