documenting-rust-code

This skill provides a comprehensive framework for documenting Rust code within the HASH repository. It enforces adherence to rustdoc conventions by establishing clear standards for doc comments, function descriptions, type specifications, and module-level documentation. Designed for developers working on the HASH codebase, the skill ensures that all public APIs are properly annotated, maintainable, and discoverable through intra-doc links, mirroring high-quality community standards found in crates like serde, time, and jiff.

• Standardizes the structure of doc comments, requiring a concise single-line summary followed by detailed explanations.

• Enforces the usage of intra-doc links for all type references to improve IDE navigation and documentation site usability.

• Defines a mandatory format for error documentation, requiring explicit # Errors sections for all fallible functions.

• Encourages the inclusion of practical examples for public APIs, ensuring they are valid and can be verified via cargo doc.

• Discourages redundant documentation of standard trait implementations like Debug, Display, or From, and prohibits separate # Returns sections in favor of inline descriptions.

• Use this skill whenever you are writing documentation for new Rust modules, functions, structs, or traits within the HASH project.

• Follow the specified patterns for simple functions with 0-2 parameters versus complex functions requiring # Arguments sections.

• Always link standard library types such as Vec or HashMap to ensure clarity and standard-compliant cross-referencing.

• Verify documentation accuracy and format by running cargo doc --no-deps --all-features locally before committing changes.

• Keep documentation comments separate from code lines to ensure readability and adhere to standard Rust style guidelines.