documenting-rust-code

# 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

```rust
/// 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

```rust
/// 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:

```rust
/// 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:

```rust
/// 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 Documentation

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

### Module Documentation

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

### Examples with Error Handling

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

## Verification

```bash
cargo doc --no-deps --all-features
```

## References

- **[references/function-documentation.md](references/function-documentation.md)**: Functions and methods documentation patterns
- **[references/type-documentation.md](references/type-documentation.md)**: Types, structs, enums, and traits documentation
- **[references/error-documentation.md](references/error-documentation.md)**: Error conditions and panics documentation
- **[references/examples-and-links.md](references/examples-and-links.md)**: Examples and intra-doc links usage