rust-api-designlisted

# Rust API Design For general idiom defaults, see `rust-patterns` first. This skill is for the specific job of designing or reviewing a **public API surface**: what to name things, what to document, and which standard traits a type should implement. ## Doc comments: what, not how or where Doc comments describe the **contract** a caller can rely on — not the implementation, and not where the API is currently used. Both leak details that change without the doc being updated. ```rust // Bad — documents implementation, which is irrelevant and goes stale fast /// Saves a `User` record to the Postgres database. /// /// This function opens a new connection and begins a transaction. It checks /// if a user with the given ID exists with a `SELECT` query... pub fn save_user(user: &User) -> Result<(), db::Error> { ... } // Good — documents the guarantee /// Atomically saves a user record. /// /// # Errors /// /// Returns `db::Error::DuplicateUsername` if the user (keyed by /// `user.username`) already exists. pub fn save_user(user: &User) -> Result<(), db::Error> { ... } ``` If implementation details genuinely matter to the caller, it's because of an effect or invariant they need to know about (e.g. "blocks the calling thread," "not safe for concurrent calls") — document *that*, not the mechanism producing it. **Avoid redundancy** — the item's name and signature already are documentation. Don't restate them: ```rust // Redundant — the signature already says this /// Parses an ip