For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/languages/rust/comments.md.
Quick start

Comments

Use rustdoc for caller-facing behavior and ordinary comments for hidden rationale.

Public documentation

Why

A Result signature does not enumerate which inputs fail or whether an operation performs I/O.

Rules

  • MUST document public items whose contract is not evident from their name and type. [review]
  • MUST describe input constraints, ownership, effects, and failure behavior. [review]
  • MUST include an Errors section for meaningful failure cases. [review]
  • MUST supply runnable rustdoc examples for consequential public behavior. [review]
  • MUST propagate example failures with Result instead of normalizing unchecked extraction in application examples. [review]
  • MUST explain the invariant of any required unsafe code at its owning boundary. [review]
  • MUST avoid comments that restate the next statement. [review]

[review]

Cargo doctests verify configured public examples. Review checks contract completeness and safety rationale.

Enforcement

Cargo doctests verify configured public examples. Review checks contract completeness and safety rationale.