[ Rust ] cargo --doc - 주석으로 프로젝트 문서 작성하기

cargo doc는 러스트 프로젝트의 문서 주석을 기반으로 HTML 형식의 문서를 자동 생성해주는 도구입니다. 이를 통해 코드에 대한 설명, 함수와 모듈의 사용법 등을 자동으로 문서화할 수 있으며, 프로젝트의 이해도와 유지보수성을 높이는 데 매우 유용합니다.

1. cargo doc 명령어의 기본 사용법

터미널에서 다음 명령어를 실행하면 현재 프로젝트의 문서가 생성됩니다:

cargo doc

• 이 명령어를 실행하면 프로젝트의 모든 소스 코드와 의존성에 대해 문서를 생성하여 target/doc 디렉터리에 저장합니다.
• 문서 파일은 HTML 형식으로 저장되며, 브라우저를 통해 확인할 수 있습니다.

2. 생성된 문서 열기: cargo doc --open

문서를 생성한 후, 직접 브라우저를 열어 문서를 확인하고 싶다면 --open 플래그를 사용할 수 있습니다:

cargo doc --open

• 이 명령어는 문서를 생성한 후 자동으로 브라우저를 열어 index.html 파일을 엽니다.
• 프로젝트의 주요 구조, 함수, 모듈, 구조체에 대한 문서를 볼 수 있습니다.

3. 문서 주석 작성하기 (///와 //!)

문서 주석을 사용하여 함수, 구조체, 모듈 등에 대한 설명을 추가할 수 있습니다. 러스트의 cargo doc는 이러한 문서 주석을 읽어 HTML 문서를 생성합니다.

함수에 대한 문서 주석 예제

/// 두 숫자의 합을 계산합니다.
///
/// # 매개변수
/// - `a`: 첫 번째 숫자
/// - `b`: 두 번째 숫자
///
/// # 반환값
/// 두 숫자의 합을 반환합니다.
fn add(a: i32, b: i32) -> i32 {
    a + b
}

• ///로 시작하는 주석은 해당 함수의 설명을 추가하는 데 사용됩니다.
• # 매개변수, # 반환값 등의 섹션을 사용하여 함수의 입력과 출력에 대해 자세히 설명할 수 있습니다.

모듈에 대한 문서 주석 예제

//! 이 모듈은 수학 관련 함수들을 포함하고 있습니다.
//! 
//! 현재 모듈에는 덧셈, 뺄셈 함수가 정의되어 있습니다.

pub mod math {
    /// 두 숫자를 더합니다.
    pub fn add(a: i32, b: i32) -> i32 {
        a + b
    }

    /// 두 숫자를 뺍니다.
    pub fn subtract(a: i32, b: i32) -> i32 {
        a - b
    }
}

• //! 주석은 모듈이나 전체 파일에 대한 설명을 추가할 때 사용합니다.
• cargo doc는 이러한 모듈 주석을 읽어 모듈의 개요를 문서화합니다.

4. 외부 크레이트(패키지)의 문서 확인

프로젝트에서 사용하는 외부 크레이트의 문서를 포함하여 확인하고 싶다면, cargo doc는 자동으로 해당 크레이트의 문서도 생성합니다.

• 프로젝트의 Cargo.toml 파일에 의존성으로 추가된 모든 크레이트의 문서가 생성됩니다.
• cargo doc --open 명령어를 사용하면 프로젝트뿐만 아니라 의존성 패키지의 문서도 쉽게 탐색할 수 있습니다.

5. 문서의 특정 부분만 생성하기

대규모 프로젝트에서 모든 문서를 한 번에 생성하는 대신 특정 패키지나 모듈의 문서만 생성하고 싶을 때는 다음과 같이 사용합니다:

cargo doc --package my_crate_name

• --package 플래그 뒤에 패키지 이름을 지정하여 해당 패키지에 대한 문서만 생성할 수 있습니다.

6. 문서 생성 최적화: 릴리스 모드 사용

디폴트로 cargo doc는 디버그 모드에서 문서를 생성합니다. 최적화된 문서를 생성하고 싶다면 --release 플래그를 사용합니다:

cargo doc --release

• 이 옵션을 사용하면 더 빠르고 최적화된 문서를 생성할 수 있습니다. 일반적으로 코드 최적화와는 관련이 없지만, 큰 프로젝트에서 문서 생성 속도에 영향을 줄 수 있습니다.

7. 테스트 도구와 함께 사용하기: cargo test --doc

러스트의 문서 주석에는 예제 코드를 포함할 수 있으며, 이 예제 코드는 cargo test 명령어를 통해 자동으로 테스트될 수 있습니다.

/// 두 숫자의 곱을 반환합니다.
///
/// # 예제
///
/// ```
/// let result = my_crate::multiply(2, 3);
/// assert_eq!(result, 6);
/// ```
pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

위처럼 문서 주석에 예제 코드를 작성하고 cargo test --doc 명령어를 실행하면, 문서 내의 모든 예제 코드가 테스트됩니다.

cargo test --doc

8. 문서 주석에서 Markdown 사용하기

러스트의 문서 주석은 Markdown 문법을 지원합니다. 이를 통해 문서를 더욱 보기 좋게 꾸밀 수 있습니다.

• 제목, 목록, 코드 블록, 링크 등 다양한 Markdown 문법을 사용해 함수, 구조체, 모듈 등에 대한 설명을 더욱 명확하게 할 수 있습니다.

예를 들어, 코드 블록을 포함한 문서 주석:

/// 이 함수는 주어진 숫자를 제곱합니다.
///
/// # 예제
///
/// ```
/// let result = my_crate::square(4);
/// assert_eq!(result, 16);
/// ```
pub fn square(x: i32) -> i32 {
    x * x
}

요약

• cargo doc: 프로젝트의 문서를 HTML로 생성.
• cargo doc --open: 문서를 생성하고 브라우저에서 열기.
• ///와 //!: 함수와 모듈에 대한 문서 주석 작성.
• cargo test --doc: 문서 주석의 예제 코드 자동 테스트.

러스트에서 cargo doc을 사용하면 프로젝트의 코드베이스에 대한 이해를 높일 수 있으며, 자동으로 문서를 관리하여 팀원들과의 협업 시에도 큰 도움이 됩니다.