rust-docs-guidelines

Rust ドキュメントのガイドライン

Rust のドキュメントを記述する際に従うべき基準です。

ガイドライン

• 重要な概念は一度だけ説明してください。それ以外のドキュメントでは、最初の説明へのドキュメント内リンクを使用してください。
• Rust のシンボル（型、関数、定数など）に言及する場合は、必ずドキュメント内リンクを使用してください。
• # Safety セクションでは、valid という語を std のポインター有効性ルールにリンクしてください。次のように記述します。

  [valid]: https://doc.rust-lang.org/std/ptr/index.html#safety
  

  ポインターやメモリーの有効性を意味する場合に限ります。valid UTF-8、有効な enum バリアント、有効な nul 終端文字、およびフィールド間の整合性が必要な値渡しの構造体は、std の定義では触れられていないため、通常の表記のままにしてください。 「返されたイテレーターの存続期間中、有効な状態を保たなければならない」のような期間を示す節も、有効性の意味そのものとは別の要件を加えるものですが、同様にリンクしてください。 コールバックのパラメーターは逆です。std のルールが対象とするのはデータポインターを介したアクセスであり、特定の ABI でアドレスを呼び出せるかどうかではありません。そのため、代わりにシグネチャが [ABI-compatible] であることを求め、次のように定義してください。

  [ABI-compatible]: https://doc.rust-lang.org/std/primitive.fn.html#abi-compatibility
  

  ドキュメント以外の // SAFETY: コメントは通常の表記のままにしてください。rustdoc ではレンダリングされないため、角括弧がそのままテキストとして残ります。
• 特定の行や行範囲への言及は避けてください。時間の経過とともに変わる可能性があります。 関数やメソッドの本体内にある特定のコード部分へドキュメントを関連付ける必要がある場合は、行コメントを使用してください。
• どのように実装するかではなく、なぜそうするのかに重点を置いてください。 特に、行コメントで自明な実装の詳細を説明するのは避けてください。
• 定数にはドキュメント内リンクを使用してください。他の項目のドキュメントに定数値を直接記述しないでください。
• 非公開項目へのドキュメント内リンクは、説明の重複よりも望ましい方法です。該当する場合は #[allow(rustdoc::private_intra_doc_links)] を追加してください。