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: