何も考えずにRustに入門する5
Rustではソースコード中のコメントからドキュメントを作成できる.
"cargo doc"コマンドがそれだが, 上の例だと"error: cannot document a package where a library and a binary have the same name. Consider renaming one or marking the target as `doc = false`"と言われて怒られる. これは実行可能ファイルとライブラリが混在しており, 名前が同じためおこる. そこで以下のように"Cargo.toml"に追記して, 実行可能ファイルの呼び名をかえて, ドキュメントの生成もしないようにする.
[[bin]] name = "main" doc = false path = "src/main.rs"
これでドキュメントの生成が可能になったのであとはコメントを追加していく.
pub mod example { //! This is a module as an example. /// Displays a message. /// /// # Examples /// /// ``` /// # use bar::example; /// example::hello(); /// ``` pub fn hello() { println!("Hello, world!"); } }
"//!"はそれを囲むモジュールの説明であり, "///"はそれにつづく関数の説明になる.
"```"で囲むことでコードを埋めこむことができる. コードスニペット中の"#"以下の行は実行はするがドキュメント上は見せないという意味になる. このコードはドキュメントとしてだけでなく, "cargo test"としたときに実際に実行されテストにかけられる. これを記述した上で先のように"cargo test"すると"Doc-tests"のところでテストが行なわれていることがわかる.
ひとつ注意として, 上のコードで"use bar::example;"としているが, この前に"extern crate bar"などとしてはいけない. その行があると, "error[E0432]: unresolved import `bar`" "Maybe a missing `extern crate bar;`?"というあべこべなエラーになる. これはむしろ"extern"していることで生じたエラーのようだ.
