RustDocの変更
RustDocは、Rustのソースファイルからドキュメントファイルを作成するためのツールです。cargo docコマンドあるいは単独で実行することで、ソースファイル内のドキュメンテーションコメントからHTMLあるいはMarkDown形式でのドキュメントファイルを作成できます。
結合されたテストによる実行速度の改善
Rust 2024では、ドキュメンテーションテストにおいて複数のコードブロックを単一のバイナリにまとめるようになり、テストの実行速度が改善されました。
ドキュメンテーションテストとは、ドキュメントファイルのドキュメンテーションコメント（///）に含まれるサンプルコードが、正しく動作するかどうかを検証するテストです。ドキュメンテーションテストの実施によって、ドキュメント中のコードが常に正しいことを保証できます。
RustDocにはテストモードがあり、この場合はドキュメントファイルの作成ではなくドキュメンテーションテストのツールとして動作します。
このドキュメンテーションテストにおいて、従来はドキュメント内のコードブロックがそれぞれ別のバイナリとして実行されており、テストの個数が多くなるとパフォーマンスに悪影響が出るようになっていました。
例えば以下のリストのように2つの関数にドキュメンテーションコメントがある場合、それぞれが別のバイナリとしてコンパイルされて実行されます。
/// Adds two numbers
///
/// ```
/// assert_eq!(doctest::add(1, 1), 2);
/// ```
pub fn add(left: u64, right: u64) -> u64 {
left + right
}
/// Subtracts two numbers
///
/// ```
/// assert_eq!(doctest::subtract(2, 1), 1);
/// ```
pub fn subtract(left: u64, right: u64) -> u64 {
left - right
}
Rust 2024では、これらのテストコードが1個のバイナリに結合されて実行されるので、テストコードの数が多くなったときのパフォーマンス劣化を抑制できます。
ただし、状況によっては複数のテストコードを単一のバイナリに結合できないときがあります。例えば、compile_failタグを付加されたコンパイルが失敗することをテストするコードがある場合です。
その場合、以下のリストのようにstandalone_crateタグをコード開始部に付加することで、個別のバイナリでの実行を指示できます。
/// ```standalone_crate /// assert_eq!(doctest::add(1, 1), 2); /// ```
入れ子になった外部ファイル取り込みにおけるパス指定の変更
Rust 2024では、入れ子になった外部ファイル取り込みで、パスの起点が変更になりました。
RustDocには、doc属性により外部ドキュメントをソースファイルに埋め込む機能があります。特に、include!マクロなどを使って外部ファイルを取り込むと、その各行がドキュメンテーションコメント「///」に変換されるので便利です。この外部ドキュメントの取り込みにおいて、それが入れ子になっているときのパスの指定方法に変更がありました。
例を挙げてみます。以下のようにパッケージが構成されているとします。
doc_include―＋
＋―src―＋
｜ ＋―lib.rs
＋―README.md
＋―MORE.md
まず、ライブラリソースlib.rsでは、以下のリストのようにパッケージルートのREADME.mdファイルを取り込んでいます。README.mdファイルは1階層上にあるので、パスには「../」を付加しています。
#[doc = include_str!("../README.md")]
このとき、README.mdファイルに以下のリストのような記述があったとします。ドキュメントとしては、このコードがテキストとして現れるだけなので、実際にはどんなコードが書かれていても問題ありません。
外部ファイル取り込み開始。
```
let _ = include_str!("MORE.md");
```
外部ファイル取り込み終了。
ここまでで、以下の図のようにドキュメントが作成されます。
しかしドキュメンテーションテストでは、README.md内のコードについてもテストが実行されます。
従来エディションでは、include_str!マクロの対象となるMORE.mdファイルは、おおもとであるlib.rsファイルに対する相対パスである必要があり、上記の指定（「../」がない）ではテストでエラーとなっていました。
Rust 2024では「読み込んだファイルからの相対パス」となるので、"MORE.md"には1階層上を意味する「../」が不要になり、以下のようにテストが問題なく実行されます。この変更により、include!マクロが記述されているファイルに対しての場所で認識すればよく、指定が直感的になりました。
% cargo test --doc
Compiling doc_include v0.1.0 (/Users/nao/Documents/codezine_rust/4/doc_include)
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.20s
Doc-tests doc_include
running 1 test
test src/../README.md - add (line 2) ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.82s
まとめ
今回は、マクロ機能に関する変更点として、フラグメント識別子の改善を中心にマクロ機能のあらましとともに紹介し、ドキュメンテーションテストの効率アップや取り込みパスの指定方法の変更について紹介しました。
今回で、Rust 2024の新機能紹介はひとまず終了です。このようにRustの改良は微に入り細にわたるものです。Rustについてなじみのない方でも、本連載を通じてRustに関心を持っていただけたならうれしいです。
