Rust Documentation Practices

Rust Documentation Practices

Comprehensive guidance on documenting Rust code in the HASH repository following rustdoc conventions.

Core Principles

Follow high-quality standards like time, jiff, and serde:

✅ DO:

• Begin every doc comment with single-line summary
• Use intra-doc links for all type references
• Document all error conditions with # Errors
• Include practical examples for public APIs
• Link standard library types: [Vec], [HashMap], etc.
• Use inline parameter descriptions for simple functions (0-2 params)
• Describe return values in main text, not separate sections

❌ DON'T:

• Document standard trait implementations (Debug, Display, From)
• Add separate # Returns sections (inline instead)
• Mention variable types already in signatures
• Use comments on same line as code
• Skip error documentation for fallible functions

Quick Reference

Basic Doc Comment

/// Retrieves an entity by its UUID.
///
/// Loads the entity from the store and verifies access permissions.
/// Returns the [`Entity`] if found and accessible.
///
/// # Errors
///
/// - [`NotFound`] if the entity doesn't exist
/// - [`AuthorizationError`] if access is denied