ドキュメントコメントの構造

  1. 簡潔な1文の要約。
  2. より詳細な説明。
  3. 特別なセクション: コード例、パニック、エラー、安全性の前提条件。
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// 文字列からキーと値のペアをパースします。
///
/// 入力文字列は `key=value` の形式でなければなりません。最初の '=' より前は
/// キーとして扱われ、それ以降は値として扱われます。
///
/// # Examples
///
/// ```
/// use my_crate::parse_key_value;
/// let (key, value) = parse_key_value("lang=rust").unwrap();
/// assert_eq!(key, "lang");
/// assert_eq!(value, "rust");
/// ```
///
/// # Panics
///
/// 入力が空の場合にパニックします。
///
/// # Errors
///
/// 文字列に `=` が含まれていない場合は `ParseError::Malformed` を返します。
///
/// # Safety
///
/// ...の場合、未定義動作を引き起こします。
unsafe fn parse_key_value(s: &str) -> Result<(String, String), ParseError>

enum ParseError {
    Empty,
    Malformed,
}

  • Rust で慣用的なドキュメントコメントは、開発者が読みやすいよう、慣例的な構造に従います。

  • ドキュメントコメントの最初の行は、関数を1文で要約したものです。簡潔に保ちましょう。rustdoc やその他のツールはこれを強く前提としており、モジュールレベルのドキュメントや検索結果では短い要約として使われます。

  • 次に、その関数の「なぜ」と「何を」について、複数段落にわたる長めの説明を記載できます。Markdown を使います。

  • 最後に、トップレベルのセクション見出しを使って内容を整理できます。ドキュメントコメントでは、# Examples、# Panics、# Errors、# Safety がセクションタイトルとしてよく使われます。Rust コミュニティでは、API の関連する側面がこれらのセクションで文書化されていることが期待されています。

  • Rust は安全性と正しさを非常に重視しています。エラー時のコードの挙動を文書化することは、信頼性の高いソフトウェアを書くうえで不可欠です。

  • # Panics: 関数がパニックする可能性がある場合は、それが起こりうる具体的な条件を必ず文書化しなければなりません。呼び出し側は何を避けるべきかを知る必要があります。

    • 質問: Result を返すことを好む言語で、なぜパニックの文書化がそれほど重要なのかをクラスに問いかけてください。

    • 回答: パニックは、回復不能なプログラミングエラーのためのものです。呼び出し側によって契約が破られた場合を除き、ライブラリはパニックすべきではありません。これらの契約を文書化することは不可欠です。

  • # Errors: Result を返す関数では、このセクションでどのような種類のエラーが、どのような状況で発生しうるかを説明します。呼び出し側は、堅牢なエラーハンドリングロジックを書くためにこの情報を必要とします。

  • # Safety コメントでは、unsafe 関数に対して満たさなければならない安全性の前提条件を文書化します。そうしないと、未定義動作が発生する可能性があります。これについては Unsafe Rust のディープダイブで詳しく扱います。