rust-docslisted

# Rust Docs A doc comment is an API contract, not narration: it tells the caller what the item does, what it requires, what it returns, and how it fails — and keeps everything the contract does not need out of the rendered docs. ## The contract test A doc comment answers what a caller must know to call the item correctly, and nothing more; it does not narrate the implementation. The test: could the body be rewritten without changing the doc comment? If not, the comment is describing the implementation, and it will rot at the first refactor. ## The first sentence carries the load Roughly fifteen words, one line, no trailing detail: it is what appears in the module index next to the item name, and the only documentation most readers will ever see. Weak then strong: ```rust,ignore /// Constructs a new instance. /// /// Takes the input, checks it, transforms it, and returns a result, or an /// error when the input was not acceptable in the way described. /// Parses a port number from a string, failing when it is out of range. ``` The weak first sentence echoes the item name and pushes the payload into a trailing paragraph; the strong one carries the whole index entry on its own. ## Module documentation `//!` at the top of the module says what the module is for and how its items fit together. A module of well-documented items with no module doc leaves the reader to infer the shape from a list of names. ## The canonical sections `# Examples`, `# Errors`, `# Panics`, `#