Rust Documentation Practices

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 ✗ Sprinkle small inline // comments; Merge these into a comprehensive doscstring if useful, otherwise remove them completely.

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
///
/// [`NotFound`]: EntityError::NotFound
/// [`AuthorizationError`]: EntityError::Authorization
pub fn get_entity(&self, id: EntityId) -> Result<Entity, Report<EntityError>> {

Intra-Doc Links

/// Updates the [`User`] using [`UserUpdateStrategy`].
///
/// See [`validation::user`] for validation rules.
///
/// [`validation::user`]: crate::validation::user

Documentation Patterns

Simple Functions (0-2 params)

Describe parameters inline:

/// Processes the `input` elements and returns filtered results.
///
/// Takes a collection of `input` elements, applies the `filter_fn`,
/// and returns a [`Vec`] containing only matching elements.

Complex Functions (3+ params)

Use explicit # Arguments section:

/// Merges multiple data sources with transformation rules.
///
/// # Arguments
///
/// * `sources` - Collection of data sources to merge
/// * `rules` - Transformation rules to apply
/// * `options` - Configuration controlling merge behavior
/// * `callback` - Optional function for each merged item

Error Docs

/// # Errors
///
/// - [`WebAlreadyExists`] if web ID is taken
/// - [`AuthorizationError`] if permission denied
///
/// [`WebAlreadyExists`]: WebError::WebAlreadyExists
/// [`AuthorizationError`]: WebError::Authorization

Module Docs

//! Entity management functionality.
//!
//! Main types:
//! - [`Entity`] - Core entity type
//! - [`EntityStore`] - Storage trait
//!
//! # Examples
//!
//! ```
//! use hash_graph::entity::Entity;
//! ```

Examples with Error Handling

/// # Examples
///
/// ```rust
/// let entities = get_entities_by_type(type_id)?;
/// assert_eq!(entities.len(), 2);
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```

Verification

cargo doc --no-deps --all-features

References

For doc-heavy tasks, read as needed:

• function-documentation.md - functions/methods
• type-documentation.md - structs/enums/traits
• error-documentation.md - errors/panics
• examples-and-links.md - examples/intra-doc links