[Rust] 문서화 주석

개요

• 주석을 포함하는 항목을 문서화
  • //!를 이용
  • 크레이트의 루트 파일이나 크레이트 혹은 모듈 전체를 문서화하는 모듈 내부에 작성
• 주석뒤에 오는 항목에 대해 문서화
  • ///를 이용
• 마크다운 표기법을 지원
• html 생성
  • cargo doc --open
  • target/doc/${crate}/index.html
• cargo test를 수행하면 주석에 있는 에제 코드가 테스트로서 실행
• pub use를 이용해 re-exports하여 실제 구조를 변경하지 않고 외부에는 변경된 것처럼 공개 가능
• 주요 구절
  • Panics
    • 패닉을 일으킬 수 있는 상황
  • Errors
    • Result 를 반환할 경우 발생할 수 있는 에러의 종류와 조건
  • Safety
    • 함수가 안전하지 않을(unsafe) 경우 이유와 상황 설명

예제

• 코드

  •  //! test1 is test1
            
     /// add is add
     ///
     /// # Examples
     ///
     /// ```
     /// assert_eq!(test1::add(1, 2), 3);
     /// ```
     pub fn add(x: i32, y: i32) -> i32 {
         x + y
     }
    

• 실행 결과
  • 
  •