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

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

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

Module Documentation

//! 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

• [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

Error Documentation Guide

Complete guide for documenting error conditions in Rust functions.

---

The # Errors Section

Every fallible function (returning Result) must document error conditions:

/// Creates a new web in the system.
///
/// Registers the web with the given parameters and ensures uniqueness.
///
/// # Errors
///
/// - [`WebAlreadyExists`] if a web with the same ID exists
/// - [`AuthorizationError`] if the account lacks permission
/// - [`DatabaseError`] if the database operation fails
///
/// [`WebAlreadyExists`]: WebError::WebAlreadyExists
/// [`AuthorizationError`]: WebError::Authorization
/// [`DatabaseError`]: WebError::Database
pub fn create_web(&mut self) -> Result<WebId, Report<WebError>> {

---

Linking Error Variants

Use intra-doc links for error enum variants:

Format

/// # Errors
///
/// - [`VariantName`] - when this happens
///
/// [`VariantName`]: ErrorType::VariantName

Example

pub enum EntityError {
    NotFound,
    Validation,
    Database,
}

/// # Errors
///
/// - [`NotFound`] if entity doesn't exist
/// - [`Validation`] if data is invalid
///
/// [`NotFound`]: EntityError::NotFound
/// [`Validation`]: EntityError::Validation

---

Runtime Errors

For errors created at runtime (not enum variants), use plain text:

/// Validates input values are unique.
///
/// # Errors
///
/// Returns a validation error if the input contains duplicates
pub fn validate_unique(values: &[String]) -> Result<(), Report<ValidationError>> {

---

External Crate Errors

For errors from external crates, describe without links:

/// Parses JSON configuration from file.
///
/// # Errors
///
/// - Returns IO error if file cannot be read
/// - Returns parse error if JSON is malformed
pub fn load_config(path: &Path) -> Result<Config, Box<dyn Error>> {

---

Panic Documentation

Use # Panics for functions that can panic:

/// Converts the entity ID to a UUID.
///
/// # Panics
///
/// Panics if the entity ID contains an invalid UUID format.
pub fn to_uuid(&self) -> Uuid {
    Uuid::parse_str(&self.id).expect("should be valid UUID")
}

Note: Prefer returning Result over panicking in library code.

---

Complete Example

/// Updates entity properties with validation.
///
/// Applies the given `changes` to the entity after validating them
/// against the entity's type schema. Returns the updated entity.
///
/// # Errors
///
/// - [`NotFound`] if entity doesn't exist
/// - [`ValidationError`] if changes violate schema
/// - [`AuthorizationError`] if caller lacks write permission
/// - [`ConcurrencyError`] if entity was modified concurrently
/// - [`DatabaseError`] if the update operation fails
///
/// # Panics
///
/// Panics if `changes` is empty (use `has_changes()` to check first).
///
/// [`NotFound`]: EntityError::NotFound
/// [`ValidationError`]: EntityError::Validation
/// [`AuthorizationError`]: EntityError::Authorization
/// [`ConcurrencyError`]: EntityError::Concurrency
/// [`DatabaseError`]: EntityError::Database
pub fn update_entity(
    &mut self,
    id: EntityId,
    changes: PropertyChanges,
) -> Result<Entity, Report<EntityError>> {
    assert!(!changes.is_empty(), "changes must not be empty");
    // implementation
}

---

Error Documentation Checklist

• [ ] # Errors section for all Result-returning functions
• [ ] Each error variant listed with bullet point
• [ ] Intra-doc links for enum variants
• [ ] Plain descriptions for runtime/external errors
• [ ] Link definitions at end of doc comment
• [ ] # Panics section if function can panic

---

Common Patterns

Multiple Error Types

/// # Errors
///
/// - [`IoError`] if file operations fail
/// - [`ParseError`] if data format is invalid
/// - [`ValidationError`] if data doesn't meet requirements
///
/// [`IoError`]: Error::Io
/// [`ParseError`]: Error::Parse
/// [`ValidationError`]: Error::Validation

Optional Operations

/// Tries to load cached data, returns `None` if not cached.
///
/// # Errors
///
/// - [`CacheError`] if cache is corrupted
/// - [`IoError`] if cache file cannot be read
///
/// Returns `Ok(None)` if data is not in cache (not an error).
///
/// [`CacheError`]: Error::Cache
/// [`IoError`]: Error::Io
pub fn try_load_cached(&self) -> Result<Option<Data>, Report<Error>> {

Async Functions

/// Fetches entity from remote store.
///
/// # Errors
///
/// - [`NetworkError`] if connection fails
/// - [`TimeoutError`] if request exceeds deadline
/// - [`NotFound`] if entity doesn't exist remotely
///
/// [`NetworkError`]: RemoteError::Network
/// [`TimeoutError`]: RemoteError::Timeout
/// [`NotFound`]: RemoteError::NotFound
pub async fn fetch_remote(&self, id: EntityId) -> Result<Entity, Report<RemoteError>> {

---

Related

• function-documentation.md - Function docs
• ../rust-error-stack/SKILL.md - Error handling patterns
• SKILL.md - Overview

Examples and Intra-Doc Links Guide

Complete guide for writing examples and using intra-doc links in Rust documentation.

---

Intra-Doc Links

Why Use Them

Intra-doc links make documentation navigable and catch broken references at compile time.

Link everything:

• Types you mention
• Related functions
• Standard library types
• Error variants

Basic Syntax

/// Updates the [`Entity`] using [`UserUpdateStrategy`].
///
/// Returns the updated [`Entity`] or [`EntityError`].
pub fn update(entity: Entity) -> Result<Entity, EntityError> {

Linking Patterns

Current module items:

/// Uses the [`LocalType`] for processing.

Other modules:

/// See [`crate::validation::user`] for validation rules.

With link definition:

/// See [`validation::user`] for validation rules.
///
/// [`validation::user`]: crate::validation::user

Standard library:

/// Returns a [`Vec`] of [`HashMap`] entries.
/// Uses [`swap_remove`] for efficient removal.
///
/// [`swap_remove`]: Vec::swap_remove

Trait methods:

/// Implements [`Iterator::next`] for sequential access.

Error variants:

/// # Errors
///
/// - [`NotFound`] if entity doesn't exist
///
/// [`NotFound`]: EntityError::NotFound

---

Writing Examples

Basic Example Structure

/// # Examples
///
/// ```rust
/// use hash_graph::entity::Entity;
///
/// let entity = Entity::new(id, properties)?;
/// assert_eq!(entity.id(), id);
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```

Example Checklist

• [ ] Imports shown (unless obvious)
• [ ] Error handling included
• [ ] Assertions demonstrate behavior
• [ ] Example compiles
• [ ] Example is minimal but complete

---

Hiding Setup Code

Use # to hide necessary setup from docs display:

/// # Examples
///
/// ```rust
/// # use hash_graph::entity::*;
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # let store = create_test_store();
/// # let type_id = EntityTypeId::new();
/// let entity = store.get_entity(type_id)?;
/// println!("Found: {}", entity.name);
/// # Ok(())
/// # }
/// ```

What renders:

let entity = store.get_entity(type_id)?;
println!("Found: {}", entity.name);

---

Error Handling in Examples

Using ? Operator

/// # Examples
///
/// ```rust
/// let result = fallible_operation()?;
/// assert!(result.is_valid());
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```

Using expect for Infallible Cases

/// # Examples
///
/// ```rust
/// let config = Config::default();
/// let value = config.get("key").expect("should have default key");
/// ```

---

Multi-Step Examples

Show realistic usage patterns:

/// # Examples
///
/// ```rust
/// # use hash_graph::entity::*;
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // Create entity
/// let mut entity = Entity::new(id, properties)?;
///
/// // Update properties
/// entity.set_property("name", "Updated")?;
/// entity.set_property("status", "active")?;
///
/// // Validate and save
/// entity.validate()?;
/// store.save(&entity)?;
/// # Ok(())
/// # }
/// ```

---

Module Documentation

Use //! for module-level docs:

//! Entity management functionality.
//!
//! This module provides types and functions for creating, updating,
//! and querying entities in the system.
//!
//! # Main Types
//!
//! - [`Entity`] - Core entity type
//! - [`EntityId`] - Unique identifier
//! - [`EntityStore`] - Storage trait
//!
//! # Examples
//!
//! ```rust
//! use hash_graph::entity::{Entity, EntityStore};
//!
//! let entity = Entity::new(id, properties)?;
//! store.save(&entity)?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```

---

Performance Notes

Document performance characteristics when relevant:

/// Retrieves all entities matching the filter.
///
/// # Performance
///
/// This operation has O(n) complexity where n is the total number of
/// entities. Uses pagination internally with 100-item pages.
///
/// For large result sets, consider using [`get_entities_stream`] which
/// provides incremental results with O(1) memory usage.
///
/// [`get_entities_stream`]: Self::get_entities_stream

---

Async Documentation

/// Processes entity asynchronously.
///
/// # Concurrency
///
/// Spawns background tasks for parallel processing. Requires multi-threaded
/// runtime. Returns when all spawned tasks complete.
///
/// # Examples
///
/// ```rust
/// # use hash_graph::entity::*;
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let result = processor.process_async(entity).await?;
/// assert!(result.is_processed());
/// # Ok(())
/// # }
/// ```
pub async fn process_async(&self, entity: Entity) -> Result<ProcessResult, Error> {

---

Complete Example

/// Validates and creates entity with type checking.
///
/// Takes `properties` and validates them against the entity's type schema.
/// If validation succeeds, creates a new [`Entity`] with generated UUID.
///
/// # Arguments
///
/// * `type_id` - Entity type defining the schema
/// * `properties` - Key-value pairs for entity properties
/// * `web_id` - Web this entity belongs to
///
/// # Errors
///
/// - [`ValidationError`] if properties don't match schema
/// - [`TypeNotFound`] if entity type doesn't exist
/// - [`DatabaseError`] if storage operation fails
///
/// # Examples
///
/// ```rust
/// # use hash_graph::entity::*;
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # let store = create_test_store();
/// # let type_id = EntityTypeId::new();
/// # let web_id = WebId::new();
/// let properties = vec![
///     ("name".to_string(), "Example".into()),
///     ("status".to_string(), "active".into()),
/// ];
///
/// let entity_id = store.create_entity(
///     type_id,
///     properties,
///     web_id,
/// )?;
///
/// let entity = store.get_entity(entity_id)?;
/// assert_eq!(entity.get_property("name"), Some(&"Example".into()));
/// # Ok(())
/// # }
/// ```
///
/// [`ValidationError`]: EntityError::Validation
/// [`TypeNotFound`]: EntityError::TypeNotFound
/// [`DatabaseError`]: EntityError::Database
pub fn create_entity(
    &mut self,
    type_id: EntityTypeId,
    properties: Vec<(String, Value)>,
    web_id: WebId,
) -> Result<EntityId, Report<EntityError>> {

---

Related

• function-documentation.md - Function docs
• error-documentation.md - Error docs
• type-documentation.md - Type docs
• SKILL.md - Overview

Function Documentation Guide

Complete guide for documenting functions and methods in Rust.

---

Documentation Structure

Every public function must have a doc comment with:

1. Single-line summary - What the function does 2. Detailed description - How it behaves 3. Parameter descriptions - Inline (simple) or explicit (complex) 4. Return value - Described in main text 5. Error conditions - # Errors section if fallible 6. Examples - # Examples section for public APIs

---

Single-Line Summary

Begin every doc comment with a clear, action-oriented summary:

✅ Good summaries:

/// Retrieves an entity by its UUID.
/// Creates a new web in the system.
/// Processes the input elements and returns filtered results.

❌ Bad summaries:

/// This function gets an entity  // "This function" is redundant
/// Entity getter                  // Too vague
/// Gets entity                    // Missing "the" or article

---

Parameter Documentation

Simple Functions (0-2 parameters)

Describe parameters inline in the main description:

/// Processes the `input` elements and returns a filtered collection.
///
/// Takes a collection of `input` elements, applies the `filter_fn` predicate
/// to each, and returns a [`Vec`] containing only the elements that passed
/// the filter condition.
pub fn process<T, F>(input: &[T], filter_fn: F) -> Vec<T>
where
    F: Fn(&T) -> bool,
{

Complex Functions (3+ parameters)

Use explicit # Arguments section with bullet points:

/// Merges multiple data sources and applies transformation rules.
///
/// This function combines data from various sources, applies the specified
/// transformation rules, and returns a unified data structure.
///
/// # Arguments
///
/// * `sources` - Collection of data sources to merge
/// * `rules` - Transformation rules to apply during merging
/// * `options` - Configuration options controlling the merge behavior
/// * `callback` - Optional function called for each merged item
/// * `context` - Additional context passed to transformation rules

---

Return Value Documentation

Always describe return values in the main description, not in a separate section:

✅ Good:

/// Retrieves an entity by its UUID.
///
/// Loads the entity from the store and verifies access permissions.
/// Returns the [`Entity`] object if found and accessible.
pub fn get_entity(&self, id: EntityId) -> Result<Entity, Report<EntityError>> {

❌ Bad:

/// Retrieves an entity by its UUID.
///
/// # Returns
///
/// The entity if found  // Don't use separate Returns section

---

Async Function Documentation

Document concurrency considerations when relevant:

/// Processes the entity asynchronously.
///
/// Fetches entity data, validates it, and stores the result. The operation
/// runs concurrently with other async tasks but maintains consistency
/// guarantees through database transactions.
///
/// # Concurrency
///
/// This function spawns multiple tasks to process entity attributes in
/// parallel. It should be called from a multi-threaded runtime context.
///
/// # Errors
///
/// - [`ValidationError`] if entity data is invalid
/// - [`DatabaseError`] if storage operation fails
pub async fn process_entity(&self, id: EntityId) -> Result<(), Report<ProcessError>> {

---

When to Skip Documentation

Skip documentation for:

• Standard trait implementations (Debug, Display, From, Into)
• Trait-derived methods (unless special behavior)
• Private helper functions (optional)
• Obvious getters/setters

// Good: No docs needed
impl Debug for MyType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // implementation
    }
}

// Good: No docs needed
impl From<MyType> for String {
    fn from(value: MyType) -> Self {
        value.to_string()
    }
}

Document trait implementations only when:

• Special behavior beyond trait definition
• Performance considerations
• Different failure modes
• Additional functionality

// Good: Documentation needed for special behavior
/// Custom serialization supporting legacy v1 format.
///
/// This implementation handles both current schema and deprecated v1
/// for backward compatibility with older data.
impl Serialize for ComplexType {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        // special implementation
    }
}

---

Performance Documentation

Add # Performance sections for performance-critical functions:

/// Retrieves all entities matching the filter.
///
/// # Performance
///
/// This operation has O(n) complexity where n is the number of entities
/// matching the filter. For large result sets, consider using the streaming
/// version [`get_entities_stream`] instead.
///
/// [`get_entities_stream`]: Self::get_entities_stream

When to document performance:

• Processing variable-sized inputs
• Hot path functions
• Complex algorithms (non-obvious complexity)
• Public APIs with performance guarantees
• Resource-intensive operations
• Operations with tradeoffs

When to skip:

• Obvious characteristics (simple getters/setters)
• Internal implementation details
• Standard library usage with no special patterns
• Non-performance-sensitive code

---

Complete Example

/// Validates and creates a new entity in the system.
///
/// Takes the provided `properties` and validates them against the entity's
/// type schema. If validation succeeds, creates a new [`Entity`] with a
/// generated UUID and stores it in the database. Returns the created entity's
/// ID.
///
/// # Arguments
///
/// * `type_id` - The entity type defining the schema
/// * `properties` - Key-value pairs for entity properties
/// * `web_id` - The web this entity belongs to
/// * `account` - Account creating the entity (for permissions)
///
/// # Errors
///
/// - [`ValidationError`] if properties don't match schema
/// - [`TypeNotFound`] if entity type doesn't exist
/// - [`AuthorizationError`] if account lacks permission
/// - [`DatabaseError`] if storage operation fails
///
/// # Examples
///
/// ```rust
/// # use hash_graph::entity::*;
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let properties = vec![
///     ("name".to_string(), "Example".into()),
///     ("description".to_string(), "An example entity".into()),
/// ];
///
/// let entity_id = store.create_entity(
///     type_id,
///     properties,
///     web_id,
///     account,
/// )?;
/// # Ok(())
/// # }
/// ```
///
/// [`ValidationError`]: EntityError::Validation
/// [`TypeNotFound`]: EntityError::TypeNotFound
/// [`AuthorizationError`]: EntityError::Authorization
/// [`DatabaseError`]: EntityError::Database
pub fn create_entity(
    &mut self,
    type_id: EntityTypeId,
    properties: Vec<(String, Value)>,
    web_id: WebId,
    account: &Account,
) -> Result<EntityId, Report<EntityError>> {

---

Related

• error-documentation.md - Documenting errors
• examples-and-links.md - Examples and links
• type-documentation.md - Types and traits
• SKILL.md - Overview

Type Documentation Guide

Complete guide for documenting types, structs, enums, and traits in Rust.

---

Struct Documentation

Basic Structure

/// Unique identifier for an entity in the system.
///
/// Combines entity UUID and web ID for precise references across the API.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct EntityId {
    pub entity_uuid: EntityUuid,
    pub web_id: WebId,
}

When to Document Fields

✅ Document when field purpose is NOT obvious:

pub struct EntityQuery {
    /// Maximum number of results to return (default: 100)
    pub limit: Option<usize>,

    /// Include deleted entities in results
    pub include_deleted: bool,
}

❌ Don't document obvious fields:

pub struct User {
    pub id: UserId,        // ID is obvious
    pub name: String,      // name is obvious
    pub email: String,     // email is obvious
}

---

Enum Documentation

Document WHY, not WHAT

✅ Good - explains purpose:

/// Entity lifecycle state.
///
/// Controls validation rules and access permissions at each stage.
pub enum EntityState {
    Draft,      // No docs needed - obvious
    Published,
    Archived,
    Deleted,
}

❌ Bad - restates the obvious:

pub enum EntityState {
    /// The draft state        // Redundant
    Draft,
    /// The published state    // Redundant
    Published,
}

When Variants Need Docs

Document variants only when they:

• Have non-obvious behavior
• Affect system state in special ways
• Have constraints or invariants

pub enum CacheStrategy {
    /// Never cache (always fetch fresh)
    None,

    /// Cache with TTL expiration
    Timed { seconds: u64 },

    /// Cache until explicitly invalidated
    Persistent,

    /// Adaptive caching based on access patterns (experimental)
    Adaptive,
}

---

Trait Documentation

Focus on contract and guarantees, not restating method signatures:

/// Store for entity data with transactional guarantees.
///
/// All operations are atomic and maintain consistency even under
/// concurrent access.
pub trait EntityStore: Send + Sync {
    /// Retrieves entity if it exists and caller has access.
    ///
    /// # Errors
    ///
    /// - [`NotFound`] if entity doesn't exist
    /// - [`AccessDenied`] if caller lacks permission
    ///
    /// [`NotFound`]: StoreError::NotFound
    /// [`AccessDenied`]: StoreError::AccessDenied
    fn get_entity(&self, id: EntityId) -> Result<Entity, Report<StoreError>>;
}

---

Newtype Pattern

Document invariants and guarantees, not the wrapping itself:

✅ Good - explains guarantees:

/// Non-empty string validated at construction.
///
/// Guaranteed to contain at least one non-whitespace character.
#[derive(Debug, Clone)]
pub struct NonEmptyString(String);

❌ Bad - states the obvious:

/// A string wrapper
pub struct NonEmptyString(String);

---

Generic Types

Document constraints and behavior, not type parameters themselves:

/// LRU cache with configurable eviction.
///
/// Evicts least-recently-used items when capacity is reached.
/// All operations are O(1) amortized.
pub struct LruCache<K, V>
where
    K: Hash + Eq,
{
    // fields...
}

---

Complex Types

Add sections only when behavior is non-obvious:

/// Temporal entity with complete version history.
///
/// # Version Storage
///
/// Versions are stored as deltas from previous state for space efficiency.
/// Full reconstruction requires replaying deltas (O(n) where n = versions).
///
/// # Querying
///
/// - `current()` - O(1), returns latest version
/// - `at_time(t)` - O(log n + m), binary search + delta replay
///
/// For frequent historical queries, use snapshot API instead.
pub struct TemporalEntity {
    // fields...
}

---

What NOT to Document

Skip documentation for:

1. Obvious structs:

   struct Point { x: f64, y: f64 }  // No docs needed

2. Standard trait implementations:

   impl Debug for MyType { ... }    // No docs needed
   impl From<A> for B { ... }       // No docs needed

3. Self-explanatory type aliases:

   type Result<T> = std::result::Result<T, Error>;  // No docs needed

4. Obvious field names:

   struct User {
       pub id: UserId,     // Don't document
       pub name: String,   // Don't document
   }

---

When TO Document

Document when:

1. Non-obvious invariants:

   /// Validated email address (RFC 5322 compliant)
   pub struct Email(String);

2. Performance characteristics:

   /// Sorted vector with O(log n) lookup
   pub struct SortedVec<T>(Vec<T>);

3. Special behavior:

   /// Cache that prefetches adjacent keys on miss
   pub struct PredictiveCache<K, V> { ... }

4. Complex state machines:

   /// Connection state. Transitions: Idle -> Active -> Closing -> Closed
   pub enum ConnectionState { ... }

---

Related

• function-documentation.md - Functions and methods
• error-documentation.md - Error types
• examples-and-links.md - Examples and links
• SKILL.md - Overview