docs: add module-level documentation and improve doc comments

17 files changed, 101 insertions, 0 deletions

diff --git a/mingling_pathf/src/config.rs b/mingling_pathf/src/config.rs
index 6758264..1199b2c 100644
--- a/mingling_pathf/src/config.rs
+++ b/mingling_pathf/src/config.rs
@@ -1,3 +1,9 @@
+//! Configuration for the module pathfinder analysis.
+//!
+//! This module defines [`PathfinderConfig`], which controls behavior such as
+//! whether dispatch-tree related types (`__internal_dispatcher_*`) should be
+//! extracted.
+
 /// Configuration for the module pathfinder analysis.
 ///
 /// Controls behavior such as whether dispatch-tree related types
diff --git a/mingling_pathf/src/error.rs b/mingling_pathf/src/error.rs
index 513ec23..70a8f6e 100644
--- a/mingling_pathf/src/error.rs
+++ b/mingling_pathf/src/error.rs
@@ -1,3 +1,9 @@
+//! Errors that can occur during the pathfinding process for Rust module resolution.
+//!
+//! This module defines all possible failure modes when traversing the module graph
+//! of a Rust project, including I/O failures, missing modules, invalid path
+//! attributes, missing entry points, and syntax parsing errors.
+
 use std::fmt;
 use std::path::PathBuf;
 
diff --git a/mingling_pathf/src/lib.rs b/mingling_pathf/src/lib.rs
index 81b2df6..557ae45 100644
--- a/mingling_pathf/src/lib.rs
+++ b/mingling_pathf/src/lib.rs
@@ -1,3 +1,6 @@
+#![allow(clippy::needless_doctest_main)]
+#![doc = include_str!("../README.md")]
+
 pub mod config;
 pub mod error;
 pub mod module_pathf;
diff --git a/mingling_pathf/src/module_pathf.rs b/mingling_pathf/src/module_pathf.rs
index c20fd82..f0a06d1 100644
--- a/mingling_pathf/src/module_pathf.rs
+++ b/mingling_pathf/src/module_pathf.rs
@@ -1,3 +1,9 @@
+//! A module for mapping Rust module paths to source files.
+//!
+//! This module provides functionality to analyze the module structure of a Rust crate
+//! and determine the effective module path for each source file, taking into account
+//! `pub use` re-exports that can cause modules to be hoisted to parent paths.
+
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use syn::{Item, UseTree};
diff --git a/mingling_pathf/src/pattern_analyzer.rs b/mingling_pathf/src/pattern_analyzer.rs
index c4b1971..3765971 100644
--- a/mingling_pathf/src/pattern_analyzer.rs
+++ b/mingling_pathf/src/pattern_analyzer.rs
@@ -1,3 +1,17 @@
+//! This module defines the core pattern analysis system used to parse and extract
+//! importable/referenceable items (like structs, enums, functions, etc.) from Rust source files.
+//!
+//! It provides a pluggable architecture via the `AnalyzePattern` trait, allowing different
+//! syntactic patterns to be registered and applied. Built-in patterns cover common structures
+//! such as basic structs, packs, groups, derives, chains, renderers, help, completion, and
+//! dispatch patterns (both standard and clap-based).
+//!
+//! The entry points are:
+//! - [`init()`] — creates a default `PatternAnalyzer` with all built-in patterns.
+//! - [`init_with_config()`] — creates a `PatternAnalyzer` with a given `PathfinderConfig`.
+//! - [`PatternAnalyzer::analyze_file()`] / [`PatternAnalyzer::analyze_file_items()`] — run
+//!   analysis on a single file.
+
 use std::collections::HashSet;
 use std::path::Path;
 
diff --git a/mingling_pathf/src/patterns.rs b/mingling_pathf/src/patterns.rs
index d0bda5d..9801e9b 100644
--- a/mingling_pathf/src/patterns.rs
+++ b/mingling_pathf/src/patterns.rs
@@ -1,3 +1,5 @@
+//! Mingling path matching patterns for command routing and field mapping.
+
 pub use basic_struct::*;
 pub use chain::*;
 pub use completion::*;
diff --git a/mingling_pathf/src/patterns/basic_struct.rs b/mingling_pathf/src/patterns/basic_struct.rs
index eeb665a..09e8e70 100644
--- a/mingling_pathf/src/patterns/basic_struct.rs
+++ b/mingling_pathf/src/patterns/basic_struct.rs
@@ -1,3 +1,7 @@
+//! The `BasicStructPattern` matches `struct` definitions in Rust source code.
+//! It identifies root-level structs and structs nested inside inline modules,
+//! returning their names and optional module path for analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/chain.rs b/mingling_pathf/src/patterns/chain.rs
index d64ed3b..6393440 100644
--- a/mingling_pathf/src/patterns/chain.rs
+++ b/mingling_pathf/src/patterns/chain.rs
@@ -1,3 +1,7 @@
+//! The `ChainPattern` matches functions annotated with `#[chain]` and
+//! extracts the generated internal struct name (e.g., `__internal_chain_<fn_name>`).
+//! This is used to track chained handler functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/completion.rs b/mingling_pathf/src/patterns/completion.rs
index ff20e0f..5427b93 100644
--- a/mingling_pathf/src/patterns/completion.rs
+++ b/mingling_pathf/src/patterns/completion.rs
@@ -1,3 +1,7 @@
+//! The `CompletionPattern` matches functions annotated with `#[completion(T)]` and
+//! extracts the generated internal struct name (e.g., `__internal_completion_<fn_name>`).
+//! This is used to track completion handler functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/dispatcher.rs b/mingling_pathf/src/patterns/dispatcher.rs
index b9f147d..6796a2c 100644
--- a/mingling_pathf/src/patterns/dispatcher.rs
+++ b/mingling_pathf/src/patterns/dispatcher.rs
@@ -1,3 +1,16 @@
+//! The `DispatcherPattern` matches invocations of the `dispatcher!` macro and
+//! extracts the generated type names from its arguments. It supports:
+//! - `Entry*` — the entry type (always generated)
+//! - `CMD*` — the dispatcher struct (always generated)
+//! - `__internal_dispatcher_*` — the dispatch tree static (when `use_dispatch_tree` is `true`)
+//!
+//! Supported forms:
+//! - Explicit: `dispatcher!("greet", CMDGreet => EntryGreet)`
+//! - Implicit: `dispatcher!("greet")` — infers `CMDGreet` and `EntryGreet`
+//! - With braces: `dispatcher! { ... }`
+//!
+//! This pattern is used to track dispatcher types for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/dispatcher_clap.rs b/mingling_pathf/src/patterns/dispatcher_clap.rs
index 2e1ec6c..1a86ad5 100644
--- a/mingling_pathf/src/patterns/dispatcher_clap.rs
+++ b/mingling_pathf/src/patterns/dispatcher_clap.rs
@@ -1,3 +1,17 @@
+//! The `DispatcherClapPattern` matches structs annotated with `#[dispatcher_clap(...)]` and
+//! extracts key items for code generation or analysis:
+//! - The entry struct name (always)
+//! - The dispatcher command struct (`CMD*`, always)
+//! - The error type, if `error = ErrorType` is specified
+//! - The help internal struct, if `help = true` is specified
+//! - The `__internal_dispatcher_*` dispatch tree static, if `use_dispatch_tree` is enabled
+//!
+//! Supported forms:
+//! - `#[dispatcher_clap("greet", CMDGreet)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, help = true)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet, help = true)] struct EntryGreet { ... }`
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/group.rs b/mingling_pathf/src/patterns/group.rs
index 99d1137..0e4b50d 100644
--- a/mingling_pathf/src/patterns/group.rs
+++ b/mingling_pathf/src/patterns/group.rs
@@ -1,3 +1,7 @@
+//! The `GroupPattern` matches the `group!` and `group_structural!` macros and
+//! extracts the type name or alias defined within them.
+//! This is used to track type groups for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/groupped_derive.rs b/mingling_pathf/src/patterns/groupped_derive.rs
index 8491121..91daaef 100644
--- a/mingling_pathf/src/patterns/groupped_derive.rs
+++ b/mingling_pathf/src/patterns/groupped_derive.rs
@@ -1,3 +1,8 @@
+//! The `GrouppedDerivePattern` matches structs, enums, and unions annotated with
+//! `#[derive(Groupped)]` or `#[derive(GrouppedSerialize)]` (or any combination
+//! with other derives). It also recurses into `mod` items to find nested types.
+//! This is used to track grouped items for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/help.rs b/mingling_pathf/src/patterns/help.rs
index 02bfa4f..628f4ac 100644
--- a/mingling_pathf/src/patterns/help.rs
+++ b/mingling_pathf/src/patterns/help.rs
@@ -1,3 +1,7 @@
+//! The `HelpPattern` matches functions annotated with `#[help]` and
+//! extracts the generated internal struct name (e.g., `__internal_help_<fn_name>`).
+//! This is used to track help functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/pack.rs b/mingling_pathf/src/patterns/pack.rs
index 83c1cee..c80fb65 100644
--- a/mingling_pathf/src/patterns/pack.rs
+++ b/mingling_pathf/src/patterns/pack.rs
@@ -1,3 +1,7 @@
+//! The `PackPattern` matches types defined by `pack!`, `pack_err!`, `pack_structural!`, and `pack_err_structural!` macros.
+//! It extracts the registered type name (e.g., `TypeName` from `pack!(TypeName = InnerType)`).
+//! This is used to track packed type definitions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/renderer.rs b/mingling_pathf/src/patterns/renderer.rs
index 054769e..c2e9ca9 100644
--- a/mingling_pathf/src/patterns/renderer.rs
+++ b/mingling_pathf/src/patterns/renderer.rs
@@ -1,3 +1,7 @@
+//! The `RendererPattern` matches functions annotated with `#[renderer]` and
+//! extracts the generated internal struct name (e.g., `__internal_renderer_<fn_name>`).
+//! This is used to track rendering functions for code generation or analysis.
+
 use syn::Item;
 
 use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/type_mapping_builder.rs b/mingling_pathf/src/type_mapping_builder.rs
index 3422af8..0965b47 100644
--- a/mingling_pathf/src/type_mapping_builder.rs
+++ b/mingling_pathf/src/type_mapping_builder.rs
@@ -1,3 +1,7 @@
+//! This module contains the matching patterns for `mingling_pathf`.
+//! It provides the core logic for analyzing crate types and generating
+//! type mapping files used by the pathfinder system.
+
 use std::collections::HashSet;
 use std::path::Path;