Rust 소스 코드 문서화

여러 언어에서 주석으로 문서를 생성하는 방법이 많이 있습니다.

예를 들어 docfx나 hugo 등이 많이 있습니다.

Rust에서는 빌드 시스템이자 패키지 관리자인 Cargo에 기본적으로 내장되어 있습니다.

오늘은 내가 만든 코드를 자동으로 문서화 시키는 방법에 대해 알아보도록 하겠습니다.

예제 코드

먼저 아래와 같이 Cargo를 통해 새로운 프로젝트를 생성하고 main.rs를 작성합니다.

$ cargo new rust_doc

enum Color {
    Red,
    Blue
}

struct Student {
    name : String,
    age : i32
}

fn add(x:i32, y:i32) -> i32 {
    x + y
}

fn main() {
    println!("Hello, world!");
}

예제 코드 문서화

여기서 주석을 사용합니다. 주의 할 점은 슬러쉬(/)가 2개 일 경우는 일반적인 주석이고 3개 일 경우에만 문서화가 됩니다.

/// 가장 좋아하는 색상은?
enum Color {
    Red,
    Blue
}

/// 학생 구조체
struct Student {
    /// 학생의 이름
    name : String,
    /// 학생의 나이
    age : i32
}

/// 
fn add(x:i32, y:i32) -> i32 {
    x + y
}

fn main() {
    println!("Hello, world!");
}

주석을 추가 하였으니 이제 Cargo를 사용해 문서화를 해보도록 하겠습니다.

$ cargo doc --open

doc 옵션

• --open
  • 문서를 빌드 한 후 브라우저를 바로 엽니다.
• --no-deps
  • 종속성에 대한 파일은 빌드하지 않습니다.
• --document-private-items
  • 문서를 비공개 항목을 포함합니다. 바이너리 대상을 문서화하는 경우 기본적으로 활성화 됩니다.