docs: add module-level documentation and improve doc comments

10 files changed, 60 insertions, 0 deletions

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};