Document all Errors.

src/errors.rs

@@ -1,3 +1,7 @@
+//! Error types for `wayfind`.
+//!
+//! All errors contain a user-friendly display method.
+
 pub(crate) mod constraint;
 pub use constraint::ConstraintError;
 

src/errors/constraint.rs

@@ -1,10 +1,43 @@
 use std::{error::Error, fmt::Display};
 
+/// Errors relating to constraints.
 #[derive(Debug, PartialEq, Eq)]
 pub enum ConstraintError {
+    /// Constraint name is already in use.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use wayfind::errors::ConstraintError;
+    ///
+    /// let error = ConstraintError::DuplicateName {
+    ///     name: "my_constraint",
+    ///     existing_type: "my_crate::constraints::A",
+    ///     new_type: "my_crate::constraints::B",
+    /// };
+    ///
+    /// let display = "
+    /// duplicate constraint name
+    ///
+    /// The constraint name 'my_constraint' is already in use:
+    ///     - existing constraint type: 'my_crate::constraints::A'
+    ///     - new constraint type: 'my_crate::constraints::B'
+    ///
+    /// help: each constraint must have a unique name
+    ///
+    /// try:
+    ///     - Check if you have accidentally added the same constraint twice
+    ///     - Ensure different constraints have different names
+    /// ";
+    ///
+    /// assert_eq!(error.to_string(), display.trim());
+    /// ```
     DuplicateName {
+        /// The name of the constraint.
         name: &'static str,
+        /// The [`type_name`](std::any::type_name) of the already existing constraint.
         existing_type: &'static str,
+        /// The [`type_name`](std::any::type_name) of the attempted new constraint.
         new_type: &'static str,
     },
 }

src/errors/decode.rs

@@ -1,10 +1,39 @@
 use std::{error::Error, fmt::Display};
 
+/// Errors relating to percent-decoding failures.
 #[derive(Debug, PartialEq, Eq)]
 pub enum DecodeError {
+    /// Invalid percent-encoding sequence encountered.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use wayfind::errors::DecodeError;
+    ///
+    /// let error = DecodeError::InvalidEncoding {
+    ///     input: "/hello%GGworld".to_string(),
+    ///     position: 6,
+    ///     character: [b'%', b'G', b'G'],
+    /// };
+    ///
+    /// let display = "
+    /// invalid percent-encoding
+    ///
+    ///    Input: /hello%GGworld
+    ///                 ^^^
+    ///
+    /// Expected: '%' followed by two hexadecimal digits (a-F, 0-9)
+    ///    Found: '%GG'
+    /// ";
+    ///
+    /// assert_eq!(error.to_string(), display.trim());
+    /// ```
     InvalidEncoding {
+        /// The unaltered input string.
         input: String,
+        /// The position in the input where the invalid encoding was found.
         position: usize,
+        /// The invalid character sequence.
         character: [u8; 3],
     },
 }

src/errors/delete.rs

@@ -1,10 +1,37 @@
 use super::route::RouteError;
 use std::{error::Error, fmt::Display};
 
+/// Errors relating to attempting to delete a route from a [`Router`](crate::Router).
 #[derive(Debug, PartialEq, Eq)]
 pub enum DeleteError {
+    /// A [`RouteError`] that occurred during the delete.
     RouteError(RouteError),
-    NotFound { path: String },
+
+    /// Path to be deleted was not found in the router.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use wayfind::errors::DeleteError;
+    ///
+    /// let error = DeleteError::NotFound {
+    ///     path: "/not_found".to_string(),
+    /// };
+    ///
+    /// let display = "
+    /// not found
+    ///
+    ///    Path: /not_found
+    ///
+    /// The specified path does not exist in the router
+    /// ";
+    ///
+    /// assert_eq!(error.to_string(), display.trim());
+    /// ```
+    NotFound {
+        /// The path that was not found in the router.
+        path: String,
+    },
 }
 
 impl Error for DeleteError {}

src/errors/insert.rs

@@ -1,13 +1,94 @@
 use super::{decode::DecodeError, route::RouteError};
 use std::{error::Error, fmt::Display};
 
+/// Errors relating to attempting to insert a route into a [`Router`](crate::Router).
 #[derive(Debug, PartialEq, Eq)]
 pub enum InsertError {
+    /// A [`RouteError`] that occurred during the insert operation.
     RouteError(RouteError),
+
+    /// A [`DecodeError`] that occurred during the insert operation.
     DecodeError(DecodeError),
-    EncodedPath { input: String, decoded: String },
-    DuplicatePath { path: String },
-    UnknownConstraint { constraint: String },
+
+    /// The path provided was percent-encoded.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use wayfind::errors::InsertError;
+    ///
+    /// let error = InsertError::EncodedPath {
+    ///     input: "/hello%20world".to_string(),
+    ///     decoded: "/hello world".to_string(),
+    /// };
+    ///
+    /// let display = "
+    /// encoded path
+    ///
+    ///      Input: /hello%20world
+    ///    Decoded: /hello world
+    ///
+    /// The router expects paths to be in their decoded form
+    /// ";
+    ///
+    /// assert_eq!(error.to_string(), display.trim());
+    /// ```
+    EncodedPath {
+        /// The original encoded input path.
+        input: String,
+        /// The decoded version of the path.
+        decoded: String,
+    },
+
+    /// The path being inserted already exists in the router.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use wayfind::errors::InsertError;
+    ///
+    /// let error = InsertError::DuplicatePath {
+    ///     path: "/existing/path".to_string(),
+    /// };
+    ///
+    /// let display = "
+    /// duplicate path
+    ///
+    ///    Path: /existing/path
+    /// ";
+    ///
+    /// assert_eq!(error.to_string(), display.trim());
+    /// ```
+    DuplicatePath {
+        /// The path that already exists in the router.
+        path: String,
+    },
+
+    /// The constraint specified in the route is not recognized by the router.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use wayfind::errors::InsertError;
+    ///
+    /// let error = InsertError::UnknownConstraint {
+    ///     constraint: "unknown_constraint".to_string(),
+    /// };
+    ///
+    /// let display = "
+    /// unknown constraint
+    ///
+    ///    Constraint: unknown_constraint
+    ///
+    /// The router doesn't recognize this constraint
+    /// ";
+    ///
+    /// assert_eq!(error.to_string(), display.trim());
+    /// ```
+    UnknownConstraint {
+        /// The name of the unrecognized constraint.
+        constraint: String,
+    },
 }
 
 impl Error for InsertError {}