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_macros/README.md  | 40 +++++++++++++++++++++++++++++++++++++++
 mingling_picker_macros/src/lib.rs |  2 ++
 2 files changed, 42 insertions(+)

(limited to 'mingling_picker_macros')

diff --git a/mingling_picker_macros/README.md b/mingling_picker_macros/README.md
index e69de29..5a3f220 100644
--- a/mingling_picker_macros/README.md
+++ b/mingling_picker_macros/README.md
@@ -0,0 +1,40 @@
+# Mingling Picker Macros
+
+Procedural macros for [Mingling Picker](https://github.com/mingling-rs/mingling/tree/main/mingling_picker), enabled by the `mingling/picker` feature.
+
+```toml
+[dependencies.mingling]
+version = "0.3.0"
+features = [
+    "picker"
+]
+```
+
+## Provided Macros
+
+### Macro `arg!`
+
+Declares a parameter definition for use with `Picker`'s `.pick()` method:
+
+```rust,ignore
+use mingling_picker_macros::arg;
+
+// Named flag with a value
+let flag = arg![name: String];
+
+// Named flag with short form
+let flag = arg![name: String, 'n'];
+
+// Named flag with alias
+let flag = arg![name: String, 'n', "nickname"];
+
+// Positional parameter
+let flag = arg![String];
+
+// Flag-only parameter (boolean)
+let flag = arg![verbose: Flag];
+```
+
+### Macro `internal_repeat!` (Internal)
+
+Internal macro used by Picker to generate `PickerPattern1..=32` and their parsing logic. Not intended for direct use.
diff --git a/mingling_picker_macros/src/lib.rs b/mingling_picker_macros/src/lib.rs
index 33bb67d..a12e3ed 100644
--- a/mingling_picker_macros/src/lib.rs
+++ b/mingling_picker_macros/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 use proc_macro::TokenStream;
 
 mod arg;
-- 
cgit