contexture rust.instructions.md

rust rules

Auto-loaded by Copilot when editing files matching **/*.rs. Generated from architectural-rules/rust/ — do not hand-edit.

Rust dependability and debug

• Destructors never fail (C-DTOR-FAIL). Drop::drop cannot return a Result; if it could panic during unwinding, you get a process abort. If cleanup can fail meaningfully (e.g. flushing a buffered writer, committing a transaction), expose an explicit close(self) -> Result<(), Error> that consumes the value, and have Drop perform a best-effort fallback (log on failure, never panic).
• Destructors that may block have an explicit non-blocking alternative (C-DTOR-BLOCK). If Drop can wait on I/O / a lock / a thread join, provide fn shutdown(self) -> ... so async / time-sensitive callers can opt out of the implicit wait. Document the blocking behavior on Drop itself.
• All public types implement Debug (C-DEBUG). #[derive(Debug)] by default; manual impl only when the derived form leaks secrets (passwords, tokens) or is too noisy. Missing Debug blocks dbg!, breaks assert_eq! failure messages, and fails generic bounds that require it.
• Debug representation is never empty (C-DEBUG-NONEMPTY). The output must let a reader distinguish two non-equal values. MyType (literally just the name) is useless; use the derived format MyType { field: value, ... } or a manual impl that surfaces identifying state.

Why: dependability and debuggability are paid for in the type definition, not at the bug site. A panicking destructor or a Debug impl that returns "" are not noticed until production, by which point the cost of fixing is enormous.

Rust documentation

• Crate-level docs (//! in lib.rs) are thorough and include runnable examples (C-CRATE-DOC). The first paragraph is a one-sentence elevator pitch that ends up in docs.rs search results.
• Every public item has at least one rustdoc example (C-EXAMPLE). Examples compile and run as doctests by default — verify with cargo test --doc. No ignore / no_run annotations except when justified (network calls, platform-specific code).
• Prose hyperlinks to relevant items (C-LINK). Use intra-doc links: [`Vec`], [`Self::method`], [`crate::module::Item`]. Do not write bare Vec in prose — link it.
• Cargo.toml includes complete metadata (C-METADATA): description, license (SPDX expression like "MIT OR Apache-2.0"), repository, documentation, readme, keywords (≤5), categories (from the docs.rs list), rust-version (MSRV).
• Maintain release notes / CHANGELOG.md documenting every significant change (C-RELNOTES). Follow [Keep a Changelog] format. Note breaking changes prominently.
• Rustdoc hides implementation noise (C-HIDDEN). Use #[doc(hidden)] on items that are public for macro-expansion reasons but not part of the API. Use #[doc(no_inline)] to prevent re-exports from cluttering listings.