Rustのコメントとドキュメントの書き方
- 作成日: 2023-01-09
- 更新日: 2023-12-24
- カテゴリ: Rust
Rustのコメントとドキュメントの書き方
Rustではコメントを書くことができます。
コメントは開発者のメモ書きです。
たとえば関数などにメモを書いておきたい時にこういったコメントを使います。
Rustのコメントには大きく分けて以下の2種類があります。
- 普通のコメント
- ドキュメントコメント
普通のコメントは普通にコメントを書きたい時に使います。
ドキュメントコメントはドキュメントを書きたい時に使うコメントです。
この記事ではこれらのコメントの書き方をコードも交えながら解説します。
関連記事
RustでJSONの読み書きを行う
RustでTCPクライアント/サーバーを作る【ソケット通信】
Rustでファイルサイズを取得する方法【std::fs::metadata】
RustのBoxの使い方【ヒープにメモリを確保！初心者向け】
RustのResultでエラーハンドリング処理を行う
RustのThread（スレッド）で並行処理をする方法
RustのVecの使い方【vec!, push, pop】
Rustのassert!の使い方【assert!, assert_eq!, assert_ne!】
普通のコメントの書き方
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
とコマンドを打ちます。
通常はこちらのコマンドの方がよく使うでしょう。
すると↓のようにページが表示されます。
たとえばmain関数のページは↓のようになります。
ドキュメントを記述するためのコメントをドキュメントコメントと言います。
これは
- スラッシュ3つのコメント
- スラッシュ2つとビックリマーク1つのコメント
の2種類があります。
スラッシュ3つのコメント
関数や構造体などにドキュメントを付けたい場合はスラッシュ3つで始まるコメントを使います。
/// # main
///
/// main関数からプログラムは始まります。
/// main関数は人気者の関数で一般的です。
///
/// ## 人気者になりたいですか？
///
/// もしあなたが人気者になりたいのなら行儀の良い関数を定義する必要があります。
/// 行儀の良い関数は使いやすく人気があります。
///
fn main() {
let result = my_func(2).unwrap();
println!("{}", result)
}
コメントの中ではマークダウン記法が使えます。
↑のように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) /* これもコメント */
}
}
↑のように普通のコメントと一緒に使うこともできます。
スラッシュ2つとビックリマーク1つのコメント
スラッシュ2つとビックリマーク1つで始まるコメントはクレートやモジュールの全体的な説明のコメントを書くときに使われます。
たとえばクレート（main.rsなど）のファイルの先頭に↓の様に書くと、
//! # これはビックリマークです
//!
//! ビックリマークの付いているコメントはどのような機能があるでしょうか？
//! ここではそれを実際に試してみたいと思います。
//! どうやらクレートのルートに文書が配置されるようです。
//!
↓のようにドキュメントの先頭に文書が差し込まれます。
モジュールに↓のようなコメントを書いておくと、
mod my_module {
//! このモジュールは私のモジュールです。
//! 開発中のためだれも使わないでください。
/// # func_1
///
/// この関数は1を返します。
///
fn func_1() -> i32 {
1
}
/// # func_2
///
/// この関数は2を返します。
///
fn func_2() -> i32 {
2
}
}
↓のようなモジュールのドキュメントができます。
ドキュメント内のコードをテストする
なんと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のコメント周りは非常によく整理されていてドキュメントを書くのもラクになってますね。
これならドキュメントを書くのも楽しいかもしれません。
🦝 < 古くなったドキュメントは
🐭 < 負の遺産