문서 주석
/// 문서화
문서 주석은(는) CoddyKit의 무료 Learn Rust Coding 강의입니다. 이것은 4개 중 3번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Learn Rust Coding 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Learn Rust Coding 강의에는 총 4개의 강의가 포함되어 있습니다.
Rust의 문서화
Rust에는 언어에 문서화 기능이 기본으로 내장되어 있습니다. 특수 주석은 cargo doc으로 생성되는 HTML 문서가 됩니다.
바깥 문서 주석
///를 사용하면 바로 뒤에 오는 항목, 즉 함수, 구조체, 열거형 등을 문서화할 수 있습니다. 주석의 텍스트는 마크다운을 지원합니다.
/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
a + b
}마크다운 서식
문서 주석은 마크다운으로 렌더링됩니다. 제목, 목록, 굵은 글씨, 링크를 모두 사용할 수 있습니다. 인라인 코드는 백틱을 사용하고, 섹션 제목은 #으로 시작합니다.
/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
width * height
}일반적인 문서 섹션
관례적인 제목을 사용하면 문서를 훑어보기 쉽습니다:
# Examples— 사용 예제# Panics— 패닉이 발생하는 경우# Errors— 반환되는 오류# Safety— 안전하지 않은 코드의 불변 조건
안쪽 문서 주석
//!를 사용하면 주석을 포함하는 바깥 항목을 문서화할 수 있습니다. 일반적으로 모듈이나 전체 크레이트를 문서화하며, 파일의 맨 위에 작성합니다.
//! # My Math Crate
//!
//! Utilities for basic arithmetic.
pub fn double(n: i32) -> i32 {
n * 2
}구조체와 필드 문서화하기
구조체 필드를 포함한 각 공개 항목에는 자체 문서 주석을 작성할 수 있습니다.
/// A point in 2D space.
pub struct Point {
/// The horizontal coordinate.
pub x: f64,
/// The vertical coordinate.
pub y: f64,
}문서 생성하기
cargo doc은 HTML 문서를 target/doc에 생성합니다. 브라우저에서 보려면 --open을 추가합니다.
cargo doc --open의존성 제외하기
기본적으로 Cargo는 의존성도 문서화합니다. --no-deps를 사용하면 자신의 크레이트에 대한 문서만 생성할 수 있습니다.
cargo doc --no-deps --open문서 내부 링크
대괄호 안에 다른 항목의 경로를 작성하여 링크할 수 있습니다. Rust가 경로를 확인하고 생성된 문서에 클릭 가능한 링크를 만듭니다.
/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
a - b
}문서화하는 이유
좋은 문서는 다음과 같은 이점을 제공합니다:
- 검색 가능한 HTML로 자동 생성됩니다
- 크레이트를 게시하면 docs.rs에 무료로 게시됩니다
- 문서의 예제가 테스트됩니다(문서 테스트)
- 팀원과 미래의 자신에게 도움이 됩니다
모듈 문서화하기
안쪽 주석과 바깥 주석을 함께 사용할 수 있습니다. 모듈 파일은 모듈을 설명하는 //!로 시작하고, 내부의 각 항목에는 ///를 사용합니다.
//! Geometry helpers.
/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
side * 4.0
}빠른 확인
바로 뒤에 오는 항목을 문서화하는 주석 문법은 무엇인가요?
복습
문서 주석에 대해 배운 내용:
///는 뒤에 오는 항목을,//!는 이를 포함하는 항목을 문서화합니다- 마크다운과
# Examples같은 섹션을 지원합니다 - 문서 내부 링크로 항목을 연결합니다
cargo doc --open으로 HTML 문서를 생성하고 확인합니다
자주 묻는 질문
“문서 주석” 강의는 무료인가요?
네 — “문서 주석” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Learn Rust Coding 강의 전체를 잠금 해제할 수 있습니다. Learn Rust Coding 강의에는 총 4개의 강의가 포함되어 있습니다.
“문서 주석”에서 뭘 배우나요?
/// 문서화 브라우저에서 직접 실행하는 실습 코드로 Learn Rust Coding을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.
Learn Rust Coding을(를) 시작하는 데 경험이 필요한가요?
사전 경험은 필요하지 않습니다. CoddyKit의 Learn Rust Coding은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 3번째 강의입니다.
“문서 주석” 강의는 얼마나 걸리나요?
대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.
이 Learn Rust Coding 강의에서 코드를 작성하고 실행할 수 있나요?
네. 모든 Learn Rust Coding 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.