コメント | Progrust Library

コメント（Comment）は、ソースコードに残す注釈です。Rustには//から行末までの行コメントと、/* */で囲むブロックコメントの2種類があります。どちらもコンパイラからは空白として扱われるため、プログラムの動作には影響しません¹。

これらとは別に、///・//!で始まるドキュメンテーションコメントがあります。こちらは単なる注釈ではなくdoc属性として扱われ、cargo docを実行するとrustdocがAPIドキュメントのHTMLに変換します¹²。

//! このクレート全体の説明（内部ドキュメント）

/// 消費税込みの価格を計算します。（外部ドキュメント: 直後の関数を説明する）
fn with_tax(price: u32) -> u32 {
    price * 110 / 100 // 税率10%を掛ける（行コメント）
}

fn main() {
    /* ブロックコメントは
       複数行をまとめて囲めます */
    println!("税込: {}円", with_tax(1000));
}

Playgroundで開く

コメントの種類

記法	種類	説明する対象
`//`	行コメント	なし（コンパイラが無視）
`/* */`	ブロックコメント	なし（コンパイラが無視）
`///`	ドキュメンテーションコメント（外部）	直後の項目
`//!`	ドキュメンテーションコメント（内部）	自分を囲む項目

外部（outer）・内部（inner）という呼び名は、説明したい対象が自分の外にあるか内にあるかに由来します。///は直後の関数や構造体を、ファイル先頭に置いた//!はそのモジュールやクレート全体を説明します¹²。

補足

ブロックコメントは入れ子にできる

C/C++と違い、Rustの/* */は入れ子を正しく数えます¹。そのため、すでに/* */を含むコードをまとめてコメントアウトしても、途中の*/で閉じてしまうことがありません。

/* 外側 /* 内側 */ ここもまだコメント */

ブロック形式と紛らわしい記法

ドキュメンテーションコメントにはブロック形式もあり、逆に見た目が似ていても通常のコメント扱いになる記法があります¹。

記法	扱い
`/** */`	ドキュメンテーションコメント（外部）のブロック形式
`/! /`	ドキュメンテーションコメント（内部）のブロック形式
`////`（スラッシュ4本以上）	通常のコメント
`/***`（アスタリスク3個以上）	通常のコメント

ブロック形式も入れ子は正しく数えますが¹、対応する/*のない*/を書くとそこでコメントが終わってしまいます（Rust 1.93で確認）。実際のコードでは///・//!の行形式が使われます。

なお////は通常のコメントなので、区切り線のつもりで書いてもドキュメントには載りません。

//// スラッシュ4本は通常のコメント
/*** アスタリスク3個も通常のコメント */

ドキュメンテーションコメント内のコード例はテストされる

ドキュメンテーションコメントの中身はMarkdownとして解釈されます¹。中に書いたコードブロックはドキュメンテーションテストとして扱われ、cargo testで実際にコンパイル・実行されます²³。ただし対象になるのはライブラリターゲットのドキュメンテーションコメントだけで、バイナリクレートに書いた例は実行されません⁴。例はクレートを外から使うコードとしてコンパイルされるため、次のようにuse宣言で対象を取り込み、公開された項目を呼び出します³。

src/lib.rs

/// 消費税込みの価格を計算します。
///
/// # Examples
///
/// ```
/// use shop::with_tax;
/// assert_eq!(with_tax(1000), 1100);
/// ```
pub fn with_tax(price: u32) -> u32 {
    price * 110 / 100
}

コメントの種類

補足

Footnotes