はじめに

---

RustのライブラリをOSSに公開するときのドキュメント周りの整備の話を記す。

ここでは、

• READMEをdocs.rsのクレートページに載せる
• README.mdに載せるコードスニペットがコンパイルするかチェックする

の2点の手法を紹介する。

設定方法

---

src/lib.rs(ライブラリのエントリポイント)に include_str!を使って、README.mdの内容をコメントとして展開する。

//!
#![doc = include_str!("../README.md")]
//!
mod hoge;
mod fuga;

基本的にはこれで設定が完了する。

これを記述しておけば、

$ cargo test

を実行するときに、README.mdの展開と、rustスニペットのコンパイルチェックおよびassertのチェックを行うことができる。 つまり、スニペットに assertを書いておけば、ライブラリ利用者にコードの状態を伝えられるだけでなく、整合性の担保も同時に行うことができる。

docをローカルで表示

---

以下のコマンドにより、ローカルでドキュメントをブラウザ表示可能

$ cargo doc --open

注意点

---

#![doc = include_str!(path)]は、コンパイル時にドキュメントをコード内に展開するので、lib.rs内の続くコードは、README.mdの行数のぶん下にずれる。

それにより、lib.rs内でのエラー表記の行数が見づらくなってしまう。

そのため、lib.rsに直接何かを定義するのは、doc埋め込みをしない場合より強く、避けたほうが良くなる。

おわりに

---

#![doc = include_str!(path)]を並べれば、他の場所のドキュメントのチェックも行うことができるだろう。 これにより、Docの変更漏れを自動で検出でき、よりコード変更に集中できるようになると考えられる。

参考

---