docs: add module-level documentation and improve doc comments

4 files changed, 72 insertions, 15 deletions

diff --git a/mingling_picker/README.md b/mingling_picker/README.md
index c83bff4..db67825 100644
--- a/mingling_picker/README.md
+++ b/mingling_picker/README.md
@@ -22,15 +22,20 @@ mingling_picker = "0.3.0"
 Provides a clean chained-call API for declaring arguments to parse:
 
 ```rust
+use mingling_picker::prelude::*;
+
 let args: Vec<&str> = vec!["--name", "Bob", "--age", "24"];
-let result = args
-    .pick(&flag![name: String])
+
+let (name, age) = args
+    .pick(&arg![name: String])
     .or(|| "Alice".to_string())
-    .pick(&flag![age: i32])
+    .pick(&arg![age: i32])
     .or(|| 24)
     .post(|num| num.clamp(0, 120))
-    .parse();
-let (name, age): (String, i32) = a.unwrap();
+    .unwrap();
+
+assert_eq!(name, "Bob".to_string());
+assert_eq!(age, 24);
 ```
 
 ## Parsing Function Library
@@ -38,5 +43,5 @@ let (name, age): (String, i32) = a.unwrap();
 Provides a pure function library `parselib` for analyzing the structure of command-line arguments.
 
 ```rust
-use mingling::picker::parselib::*;
+use mingling_picker::parselib::*;
 ```
diff --git a/mingling_picker/src/lib.rs b/mingling_picker/src/lib.rs
index afc7aca..ffa6e13 100644
--- a/mingling_picker/src/lib.rs
+++ b/mingling_picker/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod builtin;
 
 mod picker;
@@ -12,16 +14,28 @@ pub use arg::*;
 mod infos;
 pub use infos::*;
 
+/// Provides the specific parsing logic for command-line arguments and common utilities,
+/// as well as customization of command-line argument styles.
 pub mod parselib;
 
+/// Parser-provided parseable command-line types
 pub mod value;
 
+/// The prelude module, which re-exports the most commonly used traits and types.
+///
+/// This module is intended to be imported with a wildcard import:
+///
+/// ```ignore
+/// use mingling_picker::prelude::*;
+/// ```
 pub mod prelude {
     pub use crate::IntoPicker;
+    pub use crate::macros::arg;
 }
 
+/// Re-export of the `mingling_picker_macros` crate
 pub mod macros {
-    pub use mingling_picker_macros::*;
+    pub use mingling_picker_macros::arg;
 }
 
 /// Provides the types necessary for implementing the `Pickable` trait
diff --git a/mingling_picker/src/parselib/style.rs b/mingling_picker/src/parselib/style.rs
index 4ea161f..3c37b2d 100644
--- a/mingling_picker/src/parselib/style.rs
+++ b/mingling_picker/src/parselib/style.rs
@@ -109,25 +109,58 @@ impl<'a> From<&'a String> for FlagStr<'a> {
     }
 }
 
+/// Defines the naming convention for command-line option names.
+///
+/// Each variant represents a different case format that can be applied
+/// to option names (e.g., long option names) during parsing or generation.
+///
+/// # Examples
+///
+/// ```
+/// # use mingling_picker::IntoPicker;
+/// use mingling_picker::parselib::ParserStyleNamingCase;
+///
+/// let case = ParserStyleNamingCase::Kebab;
+/// assert_eq!(
+///     case.convert("brew_coffee".to_string()),
+///     "brew-coffee".to_string()
+/// );
+/// ```
 #[repr(u8)]
 #[derive(Default, Clone, Copy, PartialEq, Eq)]
 pub enum ParserStyleNamingCase {
-    /// snake_case format (e.g., `brew_coffee`)
+    /// snake_case format: words are separated by underscores, all lowercase.
+    ///
+    /// Example: `brew_coffee`
     #[default]
     Snake,
-    /// camelCase format (e.g., `brewCoffee`)
+    /// camelCase format: first word is lowercase, subsequent words are capitalized.
+    ///
+    /// Example: `brewCoffee`
     Camel,
-    /// PascalCase format (e.g., `BrewCoffee`)
+    /// PascalCase format: every word starts with an uppercase letter.
+    ///
+    /// Example: `BrewCoffee`
     Pascal,
-    /// kebab-case format (e.g., `brew-coffee`)
+    /// kebab-case format: words are separated by hyphens, all lowercase.
+    ///
+    /// Example: `brew-coffee`
     Kebab,
-    /// dot.case format (e.g., `brew.coffee`)
+    /// dot.case format: words are separated by dots, all lowercase.
+    ///
+    /// Example: `brew.coffee`
     Dot,
-    /// Title Case format (e.g., `Brew Coffee`)
+    /// Title Case format: words are separated by spaces, each word capitalized.
+    ///
+    /// Example: `Brew Coffee`
     Title,
-    /// lower case format (e.g., `brew coffee`)
+    /// lower case format: words are separated by spaces, all lowercase.
+    ///
+    /// Example: `brew coffee`
     Lower,
-    /// UPPER CASE format (e.g., `BREW COFFEE`)
+    /// UPPER CASE format: words are separated by spaces, all uppercase.
+    ///
+    /// Example: `BREW COFFEE`
     Upper,
 }
 
diff --git a/mingling_picker/src/parselib/utils.rs b/mingling_picker/src/parselib/utils.rs
index 726346c..47c5b55 100644
--- a/mingling_picker/src/parselib/utils.rs
+++ b/mingling_picker/src/parselib/utils.rs
@@ -3,6 +3,11 @@ use crate::{
     parselib::{MaskedArg, ParserStyle},
 };
 
+/// Builds a list of possible flag strings for the given argument info
+///
+/// This function generates formatted flag strings (e.g., `-h`, `--help`) from the short flag,
+/// long flag, and any aliases defined in the argument info. The long flag and alias names
+/// are converted according to the style's naming case convention before being formatted.
 #[inline(always)]
 pub fn build_possible_flags(style: &ParserStyle, arg_info: &PickerArgInfo) -> Vec<String> {
     let mut possible_flags = vec![];