Rustでドキュメントテストを書く - 気ままに技術勉強ブログ

最近、Rustでドキュメントテストが書けること（ドキュメントテストの書き方）を知ったので、そのことを備忘を兼ねて書いていきます。

Rustのテストについて色々なサイトで説明をされてますが、以下のようなユニットテストの説明が多いかと思います。

例えばライブラリで以下のように記述して

pub fn add_two(num: u8) -> u8 {
    num + 2
}

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn it_works() {
        assert_eq!(add_two(3), 5);
    }
}

ターミナルやコマンドプロンプトでcargo testを実行すると

※クレート名は"sample"という名前にしてます。

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests sample

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

みたいな出力が得られます。

それに対してドキュメントテストをしたい場合は以下のように記述します

※クレート名は上記と同じく"sample"という名前です。

/// 引数の値に2を加算して返す
/// ```
/// let result = sample::add_two(3);
/// assert_eq!(result, 5);
/// ```
pub fn add_two(num: u8) -> u8 {
    num + 2
}

このように書いてcargo testを実行すると得られる出力は

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests sample

running 1 test
test src\lib.rs - add_two (line 2) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.79s

と、Doc-testの所にテストしたという記述が現れました。

上の例を見ると、コメントの中にコードを書き、" ``` "で囲うとそれがテストと認識されてドキュメントテストができるようですが、コメントの形式はどんなものでも良いのでしょうか？色々試してみます。

// 引数の値に2を加算して返す
// ```
// let result = sample::add_two(3);
// assert_eq!(result, 5);
// ```
pub fn add_two(num: u8) -> u8 {
    num + 2
}

これはNG（ドキュメントテストがされない）でした。

他に色々やってみた結果

ドキュメントテストされるコメントの形式
- ///のコメント
- //!のコメント
ドキュメントテストされないコメントの形式
- //のコメント
- /* */のコメント

つまり、ドキュメントーションコメントの中で" ``` "でコードを囲った時に、そのコードがドキュメントテストの対象になるということですね。

以上、Rustでドキュメントテストを書く方法についてでした。