ドキュメンテーション

Rustのドキュメント機能を学びます。

ドキュメントコメント

アイテムのドキュメント（///）

#![allow(unused)]
fn main() {
/// 2つの数値を加算します。
///
/// # Arguments
///
/// * `a` - 1つ目の数値
/// * `b` - 2つ目の数値
///
/// # Returns
///
/// 2つの数値の合計
///
/// # Examples
///
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
}

モジュール/クレートのドキュメント（//!）

#![allow(unused)]
fn main() {
//! # My Crate
//!
//! `my_crate` は便利な機能を提供するクレートです。
//!
//! ## 使い方
//!
//! ```rust
//! use my_crate::add;
//! let sum = add(1, 2);
//! ```

/// 加算関数
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
}

ドキュメントのセクション

よく使うセクション

#![allow(unused)]
fn main() {
/// 短い説明。
///
/// 詳しい説明をここに書きます。
/// 複数行にわたって書けます。
///
/// # Arguments
///
/// 引数の説明
///
/// # Returns
///
/// 戻り値の説明
///
/// # Errors
///
/// エラーが発生する条件
///
/// # Panics
///
/// パニックする条件
///
/// # Examples
///
/// 使用例
///
/// # Safety
///
/// unsafeな理由（unsafe関数の場合）
pub fn some_function() {}
}

ドキュメント生成

# ドキュメント生成
cargo doc

# 生成してブラウザで開く
cargo doc --open

# 依存クレートも含める
cargo doc --document-private-items

ドキュメントテスト

Examplesに書いたコードは自動的にテストされます。

#![allow(unused)]
fn main() {
/// 除算を行います。
///
/// # Examples
///
/// ```
/// let result = divide(10, 2);
/// assert_eq!(result, Some(5));
/// ```
///
/// ゼロで割るとNoneを返します：
///
/// ```
/// let result = divide(10, 0);
/// assert_eq!(result, None);
/// ```
pub fn divide(a: i32, b: i32) -> Option<i32> {
    if b == 0 {
        None
    } else {
        Some(a / b)
    }
}
}

# ドキュメントテストを実行
cargo test --doc

テストを隠す

#![allow(unused)]
fn main() {
/// # Examples
///
/// ```
/// # // この行はドキュメントに表示されない
/// # fn setup() -> i32 { 42 }
/// let value = setup();
/// assert_eq!(value, 42);
/// ```
}

コンパイルのみ（実行しない）

#![allow(unused)]
fn main() {
/// ```no_run
/// // コンパイルはするが実行しない
/// std::process::exit(1);
/// ```
}

コンパイルエラーを期待

#![allow(unused)]
fn main() {
/// ```compile_fail
/// let x: i32 = "hello";
/// ```
}

構造体のドキュメント

#![allow(unused)]
fn main() {
/// ユーザーを表す構造体。
///
/// # Examples
///
/// ```
/// use my_crate::User;
///
/// let user = User::new("太郎".to_string(), 25);
/// assert_eq!(user.name(), "太郎");
/// ```
pub struct User {
    /// ユーザー名
    name: String,
    /// 年齢
    age: u32,
}

impl User {
    /// 新しいユーザーを作成します。
    ///
    /// # Arguments
    ///
    /// * `name` - ユーザー名
    /// * `age` - 年齢
    pub fn new(name: String, age: u32) -> Self {
        Self { name, age }
    }

    /// ユーザー名を返します。
    pub fn name(&self) -> &str {
        &self.name
    }
}
}

リンク

#![allow(unused)]
fn main() {
/// [`Vec`]を使った例。
///
/// 詳細は[`std::collections::HashMap`]を参照。
///
/// [`add`]関数も参照してください。
pub fn example() {}

/// 加算関数
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
}

ドキュメントのベストプラクティス

1. 最初の行は簡潔に

#![allow(unused)]
fn main() {
/// ファイルを読み込んで内容を返します。
///
/// 詳しい説明...
}

2. Examplesは動作するコードを

#![allow(unused)]
fn main() {
/// # Examples
///
/// ```
/// use my_crate::Config;
///
/// let config = Config::default();
/// assert!(config.is_valid());
/// ```
}

3. 公開APIは必ずドキュメント化

#![allow(unused)]
#![deny(missing_docs)]  // ドキュメントがないとエラー

fn main() {
/// 公開関数
pub fn public_function() {}
}

まとめ

確認テスト

次のドキュメント: 05_async_basics.md