[ Rust ] //, /**/, ///, //! - 주석 달기

러스트에서 주석은 코드의 가독성을 높이고, 코드의 의도나 설명을 추가하는 데 사용됩니다. 주석은 컴파일러에 의해 무시되며, 코드 실행에 영향을 주지 않습니다. 러스트에서는 한 줄 주석과 블록 주석을 사용할 수 있습니다.

1. 한 줄 주석 (//)

한 줄 주석은 // 뒤에 텍스트를 작성하여 코드의 한 줄에 설명을 추가할 때 사용합니다. 주로 짧은 설명이나 메모를 남기기에 좋습니다.

fn main() {
    // 이 함수는 프로그램의 시작점입니다.
    println!("Hello, Rust!"); // 화면에 메시지를 출력합니다.
}

위 예제에서 // 뒤에 작성된 내용은 모두 주석으로 간주되며, 컴파일러가 무시합니다.

2. 블록 주석 (/* */)

블록 주석은 여러 줄에 걸쳐 주석을 작성할 때 사용하며, /*로 시작하고 */로 끝납니다. 이 방식은 긴 설명이나 여러 줄에 걸친 메모를 남길 때 유용합니다.

fn main() {
    /*
    이 블록 주석은 여러 줄에 걸쳐
    작성할 수 있습니다.
    프로그램의 구조나 복잡한 로직을 설명할 때 사용합니다.
    */
    println!("Hello, Rust!");
}

블록 주석 중첩

러스트에서는 블록 주석을 중첩할 수 있습니다. 따라서 주석을 사용하는 코드 블록 내에서 또 다른 주석을 추가할 수 있습니다.

fn main() {
    /* 
        이 블록 주석은 중첩이 가능합니다.
        /* 내부에 또 다른 블록 주석을 사용할 수 있습니다. */
    */
    println!("Hello, Rust!");
}

3. 문서 주석 (/// 및 //!)

러스트에는 문서 주석이라는 특별한 주석 타입이 있습니다. 문서 주석은 함수, 구조체, 모듈 등에 대한 설명을 추가하여 자동으로 문서화할 수 있게 도와줍니다. 문서 주석은 /// 또는 //!를 사용합니다.

• ///: 아이템(함수, 구조체, 모듈 등)에 대한 설명을 추가합니다. 보통 함수나 구조체의 바로 위에 작성하여 설명을 덧붙입니다.
• //!: 모듈이나 파일 전체에 대한 설명을 추가합니다. 파일의 맨 위 또는 모듈의 선언 바로 위에 작성합니다.

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

fn main() {
    let result = add(2, 3);
    println!("Result: {}", result);
}

문서 주석으로 문서 생성하기

러스트의 cargo doc 명령어를 사용하면 문서 주석을 기반으로 HTML 문서를 자동으로 생성할 수 있습니다. 이를 통해 프로젝트의 함수와 구조체 등에 대한 문서를 쉽게 만들고 공유할 수 있습니다.

cargo doc --open

이 명령을 실행하면 프로젝트의 문서가 HTML 형식으로 생성되고 브라우저에서 열리게 됩니다.

요약

• 한 줄 주석: // 뒤에 텍스트를 작성하여 코드의 한 줄에 주석을 추가합니다.
• 블록 주석: /* */ 사이에 여러 줄 주석을 작성할 수 있으며, 중첩이 가능합니다.
• 문서 주석: /// 또는 //!를 사용하여 함수, 구조체, 모듈 등에 대한 설명을 문서화할 수 있습니다.

러스트의 주석 기능을 잘 활용하면 코드의 가독성을 높이고, 프로젝트의 유지보수성을 향상시킬 수 있습니다.