Rustのコメントとドキュメントの書き方

620, 2023-01-09

目次

Rustのコメントとドキュメントの書き方

Rustではコメントを書くことができます。
コメントは開発者のメモ書きです。
たとえば関数などにメモを書いておきたい時にこういったコメントを使います。

Rustのコメントには大きく分けて以下の2種類があります。

  • 普通のコメント

  • ドキュメントコメント

普通のコメントは普通にコメントを書きたい時に使います。
ドキュメントコメントはドキュメントを書きたい時に使うコメントです。

この記事ではこれらのコメントの書き方をコードも交えながら解説します。

普通のコメントの書き方

Rustの普通のコメントは以下の2種類があります。

  • 行コメント

  • ブロックコメント

行コメントはスラッシュ2つで始まるコメントです。

// コメントです。
// コメントです。
// コメントです。

ブロックコメントはスラッシュとアスタリスクで始まるコメントです。

/*
コメントです。
コメントです。
コメントです。
*/

行コメント

行コメントは半角スラッシュ2つで始まります。
これはコードにコメントを書くときに使われるポピュラーなコメントです。
コードの行末に書いたり、何行かまとめてコメントを書きたい時に使われます。

let n = 1;  // こういう感じでお尻にコメントを付けます。

// これは私のif文です。
// だれもいじらないでください。
if n < 2 {
    println!("under of two");
}

行コメントはブロックコメントよりも優先度が高く、ブロックコメントをコメントアウトすることができます。

ブロックコメント

古のC言語時代から人気のあるコメントスタイルです。
これは複数行のテキストをまとめてコメントにしたい時に優れています。

/* ここの処理はとてもエレガントだ。
   私の知的好奇心を満足させる。
   だが私は不満足だ。満たされない。 */
let n = 1 * 2 * 3;

Rustでは行コメントの方がよく使われるようです。

ドキュメントコメント

Rustではドキュメントをコードから生成することができます。
これは簡単でCargoで

$ cargo doc

を実行するだけです。
ドキュメントをブラウザで開いて確認したい場合は

$ cargo doc --open

とコマンドを打ちます。
通常はこちらのコマンドの方がよく使うでしょう。
すると↓のようにページが表示されます。

rust_doc-root

たとえばmain関数のページは↓のようになります。

rust_doc-main

ドキュメントを記述するためのコメントをドキュメントコメントと言います。
これは

  • スラッシュ3つのコメント

  • スラッシュ2つとビックリマーク1つのコメント

の2種類があります。

スラッシュ3つのコメント

関数や構造体などにドキュメントを付けたい場合はスラッシュ3つで始まるコメントを使います。

/// # main
///
/// main関数からプログラムは始まります。  
/// main関数は人気者の関数で一般的です。  
///
/// ## 人気者になりたいですか?
///
/// もしあなたが人気者になりたいのなら行儀の良い関数を定義する必要があります。  
/// 行儀の良い関数は使いやすく人気があります。  
///
fn main() {
    let result = my_func(2).unwrap();
    println!("{}", result)
}
rust_doc-main

コメントの中ではマークダウン記法が使えます。
↑のようにmain関数にコメントを付けると、ドキュメントでmain関数を説明する文書になります。

/// # my_func
///
/// my_funcは単純な関数です。  
/// 引数のnの値を2倍にして返します。  
/// nが0より下ならエラーを返します。  
///
/// # Examples
///
/// ```
/// let result = my_func(2).unwrap();
/// assert_eq!(result, 4);
/// ```
///
fn my_func(n: i32) -> Result<i32, &'static str> {
    // nが0より下なら
    if n < 0 {
        Err("invalid number")  // エラーを発生させる
    } else {
        Ok(n * 2)  /* これもコメント */
    }
}

↑のように普通のコメントと一緒に使うこともできます。

rust_doc-my-func

スラッシュ2つとビックリマーク1つのコメント

スラッシュ2つとビックリマーク1つで始まるコメントはクレートやモジュールの全体的な説明のコメントを書くときに使われます。
たとえばクレート(main.rsなど)のファイルの先頭に↓の様に書くと、

//! # これはビックリマークです
//! 
//! ビックリマークの付いているコメントはどのような機能があるでしょうか?  
//! ここではそれを実際に試してみたいと思います。  
//! どうやらクレートのルートに文書が配置されるようです。
//!

↓のようにドキュメントの先頭に文書が差し込まれます。

rust_doc-root-crate

モジュールに↓のようなコメントを書いておくと、

mod my_module {
    //! このモジュールは私のモジュールです。  
    //! 開発中のためだれも使わないでください。  

    /// # func_1
    /// 
    /// この関数は1を返します。
    /// 
    fn func_1() -> i32 {
        1
    }

    /// # func_2
    /// 
    /// この関数は2を返します。
    /// 
    fn func_2() -> i32 {
        2
    }
}

↓のようなモジュールのドキュメントができます。

rust_doc-my-module

ドキュメント内のコードをテストする

なんとRustではドキュメントに書かれているコードを実行できます。
これは

$ cargo test

で実行されます。

ですがcargo newで作成したバイナリでは実行できません。
cargo new --libで作成したライブラリでは実行できます。

↓のようにライブラリを作成して、

$ cargo new doc_lib --lib

↓のようにsrc/lib.rsにコードを書きます。

/// # ドキュメントコードの実行テストです
///
/// このライブラリは  
/// $ cargo new doc_lib --lib  
/// で作成されました。  
///
/// ```
/// use doc_lib::get_one;
///
/// let result = get_one();
/// assert_eq!(result, 1);
/// ```
pub fn get_one() -> i32 {
    1
}

そしてcargo testを実行します。

$ cargo test
    Finished test [unoptimized + debuginfo] target(s) in 0.01s
     Running unittests (target\debug\deps\doc_lib-a07aa687dcd56e27.exe)

running 0 tests

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

   Doc-tests doc_lib

running 1 test
test src\lib.rs - get_one (line 7) ... ok

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

1 passedになってますね。
ドキュメントのコードが実行されてパスしているということになります。
このようにRustではドキュメント内にコードを埋め込むことができます。

おわりに

今回はRustのコメントとドキュメントの書き方を解説しました。
Rustのコメント周りは非常によく整理されていてドキュメントを書くのもラクになってますね。
これならドキュメントを書くのも楽しいかもしれません。

(^ _ ^)

古くなったドキュメントは

(・ v ・)

負の遺産



この記事のアンケートを送信する