コメントには普通のコメントとドキュメントコメントの2つがあります。
普通のコメント
行単位なら//を行頭に置き、ブロック単位なら/* */で囲みます。
// 行単位コメント
/* ブロックレベルな
コメント */ドキュメントコメント
ドキュメントコメントには///と//!があります。違いは、前者は後に続く要素に対してのコメントに対して、後者はそれらを含むモジュールレベルのコメントになります。また、それぞれのコメントはマークダウン記法でコメントを記述します。
コードブロックの言語はデフォルトでrustが設定されます。もし、それ以外の言語だと知らせたい時は、```javascriptのように設定できます。
//! plus-one module
//!
//! # Example
//!
//! ```
//! let x = 1;
//!
//! assert_eq!(plus_one::plus_one(x), 2);
//! ```
/// plus_one function
///
/// Add 1 to the given value
///
/// # Example
///
/// ```
/// let x = 1;
///
/// assert_eq!(plus_one::plus_one(x), 2);
/// ```
///
pub fn plus_one(num: i32) -> i32 {
num + 1
}この結果はcargo doc --openでブラウザで見られます。
コードブロックに置いた Rust なコードは（ライブラリの場合）テスト対象になります。上記のcargo testと実行した時、let xから始まるコードブロックのassert_eq!はtrueで無ければテストが失敗してしまうので注意が必要です。ちなみに、ドキュメントテストだけを実行したい用にcargo test --docがあります。
// ...
Doc-tests plus-one
running 1 test
test src/lib.rs - plus_one (line 9) ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
コードブロックのコードの中身を順番に説明したいような場合もテストが通るコードが要求される為すべてを記述する必要があります。ですが、毎回全てを記載するのはやや単調かもしれません。
そんな場合はコードブロックの今はいらない行の頭に#を置くことで、その部分は今はいらないことや、ドキュメントページでその部分を隠すことができます。
例えば以下のようなコードブロックの場合、
/// ```
/// let one = 1;
/// # let two = 2;
/// # let three = 3;
/// ```ドキュメントページで出力されるのは、
let one = 1;だけになります。
