コメント

コメントには普通のコメントとドキュメントコメントの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;

だけになります。