Rustdoc

Rust 中的所有語言項目都能以特殊的 /// 語法來描述使用方法。

/// Determine whether the first argument is divisible by the second argument.
///
/// If the second argument is zero, the result is false.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;  // Corner case, early return
    }
    lhs % rhs == 0     // The last expression in a block is the return value
}

系統會將內容視為 Markdown。所有已發布的 Rust 程式庫 Crate，都會使用 rustdoc 工具自動記錄於 docs.rs 中。這種記錄 API 中所有公開項目的模式是慣用做法。

向學生展示針對 rand Crate 產生的文件，路徑如下：docs.rs/rand。
本課程未在投影片中加入 rustdoc 只是為了節省空間，但在實際程式碼中不應這麼做。
文件內註解會在稍後討論 (在模組相關頁面中)，因此這裡不需提到。
Rustdoc 註解可包含能使用 cargo test 執行及測試的程式碼片段。我們會在「測試」一節討論這些測試。

Comprehensive Rust 🦀

Rustdoc