1 files changed, 21 insertions, 3 deletions

diff --git a/src/normalizer.rs b/src/normalizer.rs
index 3ad3da2..13fd087 100644
--- a/src/normalizer.rs
+++ b/src/normalizer.rs
@@ -1,22 +1,33 @@
+//! Lexical path normalization.
+//!
+//! A [`Normalizer`] resolves paths relative to an origin base and returns a
+//! [`NormalizedPath`] with both absolute and root-relative representations.
+
 use core::fmt;
 use std::{
     env,
     path::{Component, Path, PathBuf},
 };
 
-#[derive(PartialEq, Eq, Hash, Clone)]
+/// A normalized path with two equivalent representations.
+#[derive(Debug, PartialEq, Eq, Hash, Clone)]
 pub struct NormalizedPath {
-    /// Path normalized and made absolute, suitable for filesystem access
+    /// Absolute normalized path, suitable for filesystem access.
     pub absolute: PathBuf,
-    /// Path normalized and made relative to root, used as identifier and for display
+    /// Normalized path made relative to the configured root.
     pub root_relative: PathBuf,
 }
 
+/// Errors that can occur while normalizing paths.
 #[derive(Debug)]
 pub enum NormalizeError {
+    /// The input path was empty.
     EmptyInput,
+    /// Normalization would escape above the filesystem root.
     EscapesFilesystemRoot(PathBuf),
+    /// Failed to read the current working directory.
     FailedToGetCurDir,
+    /// The path contained an invalid additional platform-specific prefix.
     InvalidMultiplePrefix(PathBuf),
 }
 
@@ -41,12 +52,16 @@ impl fmt::Display for NormalizeError {
 
 impl std::error::Error for NormalizeError {}
 
+/// Resolves and normalizes paths relative to a root and origin base.
 pub struct Normalizer {
     root: PathBuf,
     origin_base: PathBuf,
 }
 
 impl Normalizer {
+    /// Creates a normalizer.
+    ///
+    /// Relative `root` and `origin_base` values are resolved against the current directory.
     pub fn new(root: &Path, origin_base: &Path) -> Result<Self, NormalizeError> {
         let cwd = env::current_dir().map_err(|_| NormalizeError::FailedToGetCurDir)?;
         Self::new_with_cwd(root, origin_base, &cwd)
@@ -59,6 +74,9 @@ impl Normalizer {
         })
     }
 
+    /// Resolves and normalizes `input`.
+    ///
+    /// Relative inputs are resolved against this normalizer's origin base.
     pub fn normalize(&self, input: &Path) -> Result<NormalizedPath, NormalizeError> {
         if input.as_os_str().is_empty() {
             return Err(NormalizeError::EmptyInput);