From dc9d5ea0026a6cb6bb477d5db8e9190a79ecb337 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Fri, 17 Jul 2026 04:04:11 +0800
Subject: docs: add module-level documentation and improve doc comments

---
 mingling_picker/src/lib.rs            | 16 +++++++++++-
 mingling_picker/src/parselib/style.rs | 49 +++++++++++++++++++++++++++++------
 mingling_picker/src/parselib/utils.rs |  5 ++++
 3 files changed, 61 insertions(+), 9 deletions(-)

(limited to 'mingling_picker/src')

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![];
-- 
cgit