Documenting Errors

Whenever a public function or method returns Result<T, E>, its documentation should include an # Errors section explaining the specific runtime conditions that produce an Err(E) value and linking to the relevant error variants.

/// Reads and validates a configuration file from `path`.
///
/// # Errors
///
/// Returns an [`Err`] if:
/// - The file cannot be opened or read ([`ConfigError::Io`]).
/// - The file exceeds the 1 MiB size limit ([`ConfigError::TooLarge`]).
/// - A line is missing a `=` delimiter ([`ConfigError::Syntax`]).
pub fn load_config(path: &Path) -> Result<Config, ConfigError> { ... }

Structuring Clear `# Errors` Documentation

Link directly to error enum variants: When E is a structured enum (such as ConfigError::Syntax), use intra-doc links ([ConfigError::Syntax]) on each bullet so callers can click straight to the variant's fields or match arms.
State whether side effects are rolled back on Err: If a mutating method (&mut self) can return Err, document whether self is left unchanged (strong exception guarantee) or partially modified on failure.
Document both the function's # Errors and the error type itself: Document each variant of the error enum so IDE hover tooltips explain the variant wherever it is matched.

#![warn(clippy::missing_errors_doc)]

/// Errors that can occur when reserving capacity in a [`QuotaPool`].
#[derive(Debug, PartialEq, Eq)]
pub enum QuotaError {
    /// The requested reservation was `0` units.
    ZeroReservation,
    /// The pool only has `remaining` units available, which is less than `requested`.
    Exhausted {
        /// Units currently available in the pool.
        remaining: u32,
        /// Units requested by the caller.
        requested: u32,
    },
}

/// Tracks a fixed resource quota across callers.
#[derive(Debug)]
pub struct QuotaPool {
    remaining: u32,
}

impl QuotaPool {
    /// Creates a new [`QuotaPool`] with `initial` available units.
    pub const fn new(initial: u32) -> Self {
        Self { remaining: initial }
    }

    /// Reserves `units` from the pool, returning the remaining balance.
    ///
    /// If this method returns [`Err`], the pool's remaining balance is left unchanged.
    ///
    /// # Errors
    ///
    /// - Returns [`QuotaError::ZeroReservation`] if `units == 0`.
    /// - Returns [`QuotaError::Exhausted`] if `units > self.remaining`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use my_crate::{QuotaPool, QuotaError};
    /// let mut pool = QuotaPool::new(100);
    /// assert_eq!(pool.reserve(40), Ok(60));
    /// assert_eq!(
    ///     pool.reserve(80),
    ///     Err(QuotaError::Exhausted { remaining: 60, requested: 80 })
    /// );
    /// ```
    pub fn reserve(&mut self, units: u32) -> Result<u32, QuotaError> {
        if units == 0 {
            return Err(QuotaError::ZeroReservation);
        }
        if units > self.remaining {
            return Err(QuotaError::Exhausted {
                remaining: self.remaining,
                requested: units,
            });
        }
        self.remaining -= units;
        Ok(self.remaining)
    }
}

fn main() {
    let mut pool = QuotaPool::new(100);
    println!("After reserving 40: {:?}", pool.reserve(40));
    println!("Attempting 80:      {:?}", pool.reserve(80));
}

After reserving 40: Ok(60)
Attempting 80:      Err(Exhausted { remaining: 60, requested: 80 })

Enforcing `# Errors` Documentation with Clippy

The Clippy lint clippy::missing_errors_doc (#![warn(clippy::missing_errors_doc)]) checks every public function returning Result<T, E> and warns if its doc comment omits the # Errors heading.

Structuring Clear # Errors Documentation

Enforcing # Errors Documentation with Clippy

Structuring Clear `# Errors` Documentation

Enforcing `# Errors` Documentation with Clippy