05. 함수·표현식·반환값·문서화 주석

이 강의에서 배우는 것

• 1fn 으로 함수를 정의하고 인자·반환 타입을 명시한다
• 2표현식과 문장의 차이를 안다
• 3명시적 return 없이 마지막 표현식으로 값을 반환한다
• 4/// 문서화 주석을 작성하고 cargo doc 으로 HTML 을 만든다
• 5튜플 반환으로 다중 값을 돌려준다

소개

Rust 의 함수는 단순하지만, 표현식 중심 언어라는 특성 때문에 다른 언어에서 온 사람이 처음엔 헷갈리는 지점이 하나 있습니다 — **마지막 줄에 세미콜론을 붙이느냐 마느냐** 가 반환값 유무를 결정합니다. 이 한 규칙만 익히면 코드가 훨씬 짧아집니다.

핵심 개념

1) 함수 기본 문법

fn add(a: i32, b: i32) -> i32 {
    a + b   // 세미콜론 없음 → 반환 값
}

2) 표현식 vs 문장

• **표현식(expression)** — 값을 만드는 것. `5`, `a + b`, `if cond { 1 } else { 2 }`, 블록 `{ let x = 1; x + 1 }`
• **문장(statement)** — 동작은 하지만 값은 만들지 않는 것. `let x = 5;`, `fn f() {}`
• 표현식에 세미콜론을 붙이면 문장이 됨 → 값이 사라짐

3) 명시적 return

조기 종료가 필요할 때 `return value;` 사용. 일반적으로는 마지막 표현식이 더 idiomatic.

4) 문서화 주석

• `///` 으로 시작하면 다음 항목에 대한 문서 주석
• Markdown 지원 — 코드 예제는 자동 doctest 가 됨
• `cargo doc --open` 으로 HTML 문서 생성·열기

핵심 예제

암묵적 반환과 명시적 return:

fn divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        return -1;     // 조기 종료
    }
    a / b             // 마지막 표현식 → 반환
}

fn main() {
    println!("{}", divide(10, 3)); // 3
    println!("{}", divide(10, 0)); // -1
}

튜플 반환으로 다중 값:

fn minmax(v: &[i32]) -> (i32, i32) {
    let mut mn = v[0];
    let mut mx = v[0];
    for &x in v {
        if x < mn { mn = x; }
        if x > mx { mx = x; }
    }
    (mn, mx)
}

fn main() {
    let (a, b) = minmax(&[3, 7, 1, 9, 4]);
    println!("min={}, max={}", a, b); // 1, 9
}

문서화 주석 — Markdown + doctest:

/// 두 수를 더해 반환합니다.
///
/// # 예제
///
/// ```
/// assert_eq!(my_crate::add(2, 3), 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

cargo doc --open       # HTML 문서 생성
cargo test --doc        # doctest 실행

자주 하는 실수

Q. 반환값이 안 나가요. 분명히 `a + b` 라고 썼는데

A. `a + b;` 처럼 세미콜론을 붙이면 문장이 돼서 값이 사라집니다. 마지막 줄은 세미콜론 없이.

Q. unit 타입 `()` 가 뭔가요?

A. 다른 언어의 void 비슷합니다. 반환 타입 생략 = `-> ()`. 함수가 의미 있는 값을 안 돌려준다는 뜻.

Q. main 함수는 반환값을 못 가지나요?

A. `fn main() -> Result<(), Box<dyn Error>>` 처럼 Result 를 반환하면 ? 연산자도 main 에서 쓸 수 있습니다. 에러 처리 강의에서 자세히.

정리

• 함수 시그니처는 인자·반환 타입을 모두 명시
• 마지막 표현식이 반환값, 세미콜론 붙이면 사라짐
• 조기 종료에 return 사용
• /// 로 작성한 주석은 cargo doc 으로 HTML 문서가 되고 doctest 도 실행됨

과제

1. 섭씨 ↔ 화씨 변환 함수 두 개를 작성하고 main 에서 호출
2. 최소·최대·평균을 한 번에 돌려주는 stats 함수를 (i32, i32, f64) 튜플로 반환하게 작성
3. /// 주석에 예제 코드를 넣고 `cargo test --doc` 으로 doctest 통과 확인