5.4. 주석 (Comments) - 100%
이제 여러분들은 몇 개의 함수들을 가지게 되었고, 주석에 대해 배우는 것은 좋은 생각입니다. 주석은 다른 프로그래머에게 여러분의 코드에 관한 것들을 설명하는데 도움을 주도록 남기는 것입니다. 컴파일러는 주석 대부분을 무시합니다.
Rust는 두 종류의 주석(한 줄 주석과 문서 주석)을 가지고 있습니다.
// 라인 주석은 '//' 뒤에 오는 모든 것이고, 그 라인 끝까지 포함됩니다.
// Line comments are anything after ‘//’ and extend to the end of the line.
let x = 5; // this is also a line comment.
let x = 5; // 이 또한 라인 주석입니다.
// 무언가에 대해 긴 설명을 적어야 한다면, 라인 주석을
// 이렇게 적을 수 있습니다. // 와 주석 사이에 공백을 하나 넣어주세요. 그래야
// 더 보기 좋아집니다.
// If you have a long explanation for something, you can put line comments next
// to each other. Put a space between the // and your comment so that it’s
// more readable.
나머지 주석의 종류는 문서 주석입니다. 문서 주석은 // 대신에 ///를 사용하고, 내용으로 마크다운 표기를 지원합니다.
/// 주어진 숫자에 1 을 더함.
/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let five = 5;
///
/// assert_eq!(6, add_one(5));
/// # fn add_one(x: i32) -> i32 {
/// # x + 1
/// # }
/// ```
fn add_one(x: i32) -> i32 {
x + 1
}
이후에 나오는 요소 대신에 가지고 있는 요소을 설명하기 위해 또다른 스타일의 문서 주석 //! 이 있습니다. creates root (lib.rs) 또는 modules root (mod.rs) 내에서 흔히 사용됩니다:
//! # 러스트 표준 라이브러리
//!
//! 러스트 표준 라이브러리는 이식성있는 러스트 소프트웨어를 개발함에 있어
//! 필수적인 런타임 기능을 제공합니다.
//!
//! # The Rust Standard Library
//!
//! The Rust Standard Library provides the essential runtime
//! functionality for building portable Rust software.
문서 주석을 작성할 때, 사용 예제를 제공하면 아주, 아주 도움이 됩니다. 여기 새로운 매크로 assert_eq!를 사용한다는 것을 알려줍니다. 이 것은 두 값을 비교해서, 서로 다르면 panic!을 발생시킵니다. 이것은 문서화에 아주 도움이 됩니다. 값이 false라면 panic!을 발생시키는 assert! 매크로도 있습니다.
문서 주석에서 HTML 문서를 생성하고, 테스트로서 코드 예제를 실행하기 위해 rustdoc 도구를 사용할 수 있습니다.