Rustdoc하구만: Rust 프로젝트 API 문서화

Rustdoc은 Rust 프로젝트의 코드 주석으로부터 자동으로 API 문서를 만들어주는 도구입니다.

Rust에서는 //와 /* */를 주석으로 사용하는데, Rustdoc을 이용해 API 문서를 만들 때는 특별한 주석을 사용합니다.

///와 //!가 문서화 주석인데요, 차이점은 // 뒤에 /와 !가 붙어있는 형태입니다.

마찬가지로, 블록 주석 /* */에 대해서도 블록 문서화 주석인 /** */와 /*! */가 있습니다.

///와 //!의 차이점은 주석을 쓰는 위치가 다르다는 것입니다.

///는 외부 문서화(Outer Documentation) 주석이라고 불리며, 주석 뒤에 있는 내용을 문서화하는데 사용됩니다.

예를 들어, /// 함수의 기능을 설명하는 데 사용할 수 있습니다.

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

문서화 주석의 특징 중 하나는 Markdown 기능으로, 이것을 이용해 전달하려는 내용을 보기 편하게 수식해 줄 수 있습니다.

위 코드에서도 # Examples으로 주석에 헤더(Header)를 넣었는데, 이렇게하면 API 문서로 출력되었을 때 문단을 나눠서 작성됩니다.

//!는 내부 문서화(Inner Documentation) 주석으로, 주석이 달린 파일을 설명하는 데 사용합니다.

주로, 크레이트(Crate)를 설명하기 위해 사용하는데, 크레이트 앞에는 아무것도 없어서 외부 문서화 주석을 사용할 수 없기 때문입니다.

//! This is my first rust crate

코드를 테스트하는 용도로, 문서화 주석 안의 코드를 실행시키는 방법도 있습니다.

cargo test 명령을 이용하면 자동으로 문서화 주석 안의 코드도 실행 시켜 테스트하지만, 문서화 주석 코드만 실행하고 싶을 때는 --doc 옵션을 이용하면 됩니다.

$ cargo test --doc

비동기 코드는 Tokio로 실행하는데, 코드 앞에 #를 붙이면 해당 줄은 API 문서에서 감춰지게 됩니다.

이를 이용해 문서에서는 핵심 코드만 보이도록 할 수 있습니다.

/// Acquires a permit from the semaphore.
///
/// # Examples
///
/// ```
/// # use qp::sync::Semaphore;
/// # #[tokio::main]
/// # async fn main() {
/// let binary_semaphore = Semaphore::new(1);
/// let permit = binary_semaphore.acquire().await;
/// # }
/// ```