ドキュメントコメント
///ドキュメント
「ドキュメントコメント」はCoddyKit上の無料Learn Rust Codingレッスンです。 これはレッスン3/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはLearn Rust Coding学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Learn Rust Codingコースには全4レッスンが含まれています。
Rustのドキュメント
Rust には、言語に組み込まれた第一級のドキュメント機能があります。特別なコメントから、cargo doc で HTML ドキュメントを生成できます。
外側のドキュメントコメント
/// を使うと、その直後にあるアイテム（関数、構造体、列挙型など）をドキュメント化できます。テキストでは Markdown を使用できます。
/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
a + b
}Markdownの書式
ドキュメントコメントは Markdown として表示されます。見出し、リスト、太字、リンクなどを使えます。インラインコードにはバッククォートを使い、セクション見出しは # で始めます。
/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
width * height
}一般的なドキュメントセクション
慣用的な見出しを使うと、ドキュメントをすばやく把握できます。
# Examples— 使用例# Panics— パニックが発生する場合# Errors— 返されるエラー# Safety— unsafe コードの不変条件
内側のドキュメントコメント
//! を使うと、それを含むアイテム（通常はモジュールまたはクレート全体）をドキュメント化できます。ファイルの先頭に記述します。
//! # My Math Crate
//!
//! Utilities for basic arithmetic.
pub fn double(n: i32) -> i32 {
n * 2
}構造体とフィールドのドキュメント化
構造体のフィールドを含む各公開アイテムには、それぞれ独自のドキュメントコメントを付けられます。
/// A point in 2D space.
pub struct Point {
/// The horizontal coordinate.
pub x: f64,
/// The vertical coordinate.
pub y: f64,
}ドキュメントの生成
cargo doc は HTML ドキュメントを target/doc に生成します。--open を追加すると、ブラウザーで表示できます。
cargo doc --open依存関係を除外する
デフォルトでは Cargo は依存関係のドキュメントも生成します。--no-deps を使うと、自分のクレートだけのドキュメントを生成できます。
cargo doc --no-deps --openドキュメント内リンク
パスを角かっこで囲んで記述すると、他のアイテムにリンクできます。Rust がパスを解決し、生成されたドキュメントにクリック可能なリンクを作成します。
/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
a - b
}ドキュメント化する理由
優れたドキュメントには次のような利点があります：
- 検索可能な HTML として自動生成される
- クレートを公開すると docs.rs で無料公開される
- ドキュメント内の例がテストされる（ドキュメントテスト）
- チームメンバーや将来の自分に役立つ
モジュールのドキュメント化
内側と外側のコメントを組み合わせます。モジュールファイルの先頭に //! でモジュールを説明し、その中の各アイテムには /// を使います。
//! Geometry helpers.
/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
side * 4.0
}理解度チェック
直後にあるアイテムをドキュメント化するコメント構文はどれですか？
まとめ
ドキュメントコメントについて学びました：
///は直後のアイテムを、//!はそれを含むアイテムをドキュメント化する- Markdown と
# Examplesなどのセクションを使用できる - ドキュメント内リンクでアイテム同士をつなげられる
cargo doc --openで HTML ドキュメントを生成して表示する
よくある質問
「ドキュメントコメント」レッスンは無料ですか？
はい。「ドキュメントコメント」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Learn Rust Codingコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Learn Rust Codingコースには全4レッスンが含まれています。
「ドキュメントコメント」で何を学びますか？
///ドキュメント ブラウザで直接実行するハンズオンコードでLearn Rust Codingを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
Learn Rust Codingを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのLearn Rust Codingは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン3/4です。
「ドキュメントコメント」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このLearn Rust Codingレッスンでコードを書いて実行できますか？
はい。すべてのLearn Rust Codingレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。