TL;DR
- パブリック API にはドキュメントを書き、コードから分からないことを書く。たとえば前提条件、不変条件、panic が起きる条件（
# Panics）、unsafe なコードが必要とする条件（# Safety）、設計判断の理由である。 - コメントはコードの近くに置き、識別子にはクロスリファレンスを付けて読みやすくする。
内容
あるクレートを別のプログラマが使うのであれば、パブリック API のドキュメントを用意する。そのプログラマには未来の自分も含まれる。
ドキュメンテーションコメント
Rust では /// または //! で、Markdown 形式のドキュメンテーションコメントを書ける（The Rust Programming Language 日本語版）。
/// 2 つの [`BoundingBox`] を正確に包含する [`BoundingBox`] を計算する
pub fn union(a: &BoundingBox, b: &BoundingBox) -> BoundingBox {
// ...
}書くときは次の点に気を付ける。
- コードはコードフォント（バッククォート）で書く
- 識別子には
[`Something`]の形でクロスリファレンスを書く。Somethingがスコープ内にあれば、ドキュメントにリンクが付く # Examplesの節にサンプルコードを書く。このコードはcargo testのときにコンパイルされ、実行される（項目30）# Panicsの節に panic を起こさないための前提条件を、# Safetyの節に unsafe なコードが必要とする前提条件を書く
書き方に迷ったら、標準ライブラリを参考にするとよい。
ドキュメントの生成と lint
cargo doc を実行すると、ドキュメンテーションコメントからドキュメントを生成できる。ドキュメントを書いたら、レンダリングされたものを読む。--open、または現在のクレートに限る --no-deps --open を付けるとすぐに開ける。
関連する lint が 2 つある。broken_intra_doc_links は、生成されたリンクがすべて有効かを確かめる。たとえば [`Polygon`] と書いたのに Polygon がスコープにないと、unresolved link to Polygon という警告が出る。missing_docs はドキュメントがあるかを確かめるが、数を満たすためだけの質の低いドキュメントが増える危険がある。これらの lint は CI で動かすとよい（項目32）。
ドキュメントを置く場所
cargo doc の出力先は target/doc だが、ドキュメントは他の場所に置いてもよい。たとえば examples/ ディレクトリには、クレートを使うプログラムを置くことが多い。これらは統合テストと同じようにビルドされて実行され（cargo run --example <name>）、API の正しい使い方を示すサンプルになる。tests/ の統合テストも同じ役割を持つ。
クレートを crates.io に公開すると、ドキュメントは docs.rs にも公開される。docs.rs のトップページは src/lib.rs の先頭にある //! コメントから作られ、crates.io にはリポジトリのトップにある README.md が表示される。
書くべきでないこと
コードから分かることはドキュメントに書かない。関数のシグネチャや型から明らかなことを書くと、コードとコメントが食い違いやすくなる。たとえば、引数 a を「BoundingBox に対する不変参照」と書いておくと、後で a を &mut BoundingBox に変えたときにコメントだけが古いまま残る。リファクタリングでコメントを直し忘れても、IDE は指摘してくれない。言い換えると、コードから明らかでないこと（前提条件、不変条件、panic、エラーの条件など）をすべて書く。コードのほうは驚き最小の原則に従うようにする。
そのメソッドを使う他のコードについても書かない。「hits.rs の衝突判定が、ピクセル単位のチェックの前にこのメソッドを使う」と書くと、hits.rs を変えたときに食い違う。代わりに「重なりがあることは衝突の必要条件だが十分条件ではないので、重なった部分にはピクセル単位のチェックが要る」のように、メソッド自身の性質として書く。これは A Philosophy of Software Design 第16章の「コメントはコードの近くに置く」「コメントは抽象的にする」という考え方と同じである。
コードを書くときの「未来形でプログラミングしよう」という助言は、ドキュメントにも当てはまる。そのため、コメントは設計判断（なぜそうしたか、なぜそうしなかったか）に焦点を当てて書く。