Rust のコメント文に感激した話

Rust を使っていて、感激したことの一つにコメント文があります。

• Rust のコメント文のドキュメント

コメント文は、上記のようにドキュメントにて丁寧な説明がされているので、改めて解説はしませんが、感激したポイントを書いていきます。

まず、以下が通常のコメント。これは普通ですよね。

// ただのコメント

興味深いのは、ドキュメント用のコメントとして、/// と //! というのがある点です。

これは Javadoc 的なものを想像してもらうといいでしょう。僕は Javadoc を初めて触った時、コードに書いたものが HTML になることにとても驚き感激しました。Rust のコメント文は、今までここがあったら良かったのにみたいな機能が盛り込まれています。

//! サンプル用設定

/// # 定数サンプル
///
/// 定数 MAX_POINTS について書きます
/// 
/// マークダウンがかけるよ
///
/// ## コードが書ける
///
/// ```rust
/// println!("{}", MAX_POINTS);
/// ```
///
/// ## 箇条書き
///
/// こんどは箇条書きをします
///
/// - list 1
/// - list 2
///
/// ----
///
pub const MAX_POINTS: u32 = 100000;

あったら良かったのに機能の一つに、上記のようにコメントをマークダウンで書くことがサポートされているという点があります。見出しやソースコードを含めることができるので、ドキュメントにおける表現の幅が広がるのです。

更に良いと思っている点は、ドキュメントの出力ツールが標準で用意されているところです。ドキュメンテーションコメントを書き、以下を実行すると、ドキュメントが target/doc フォルダに出力されます。

$ cargo doc

出力されたドキュメントは、なかなか見やすく、もちろんマークダウンも反映されています。

また、//! で包括的なドキュメンテーションコメントを書くことも出来、クレート自体のコメントを記述することも出来ます。

//! 包括的なドキュメンテーションコメント

それで、これが最高なのですが、これらドキュメンテーションコメントを IntelliJ の IDE で書くと、きちんとコメント内のマークダウンがそれなりにハイライトしてくれるのですね。

今まで触ったプログラミング言語の中で一番コメント書きやすく、書いてて楽しいです。もっと言うと、これマークダウンで書けるので、プログラミングそっちのけで、静的サイトジェネレーターとして使ってもいいかもしれません。