From 13408e79b940e9a33ca593ed30d1b20c54e01234 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Tue, 30 Jun 2026 18:05:05 +0800
Subject: feat(docs): add Chinese and English documentation for Mingling
tutorials
Add comprehensive documentation covering Declare a Dispatcher, Declare a
Chain, Rendering Results, Multi-Command Program, Argument Parsing with
Picker and Clap, Program Setup, Error Handling, Help Info, Resource
System, Exit Code Control, Hook System, Testing, Completion, Structural
Rendering, and Core Concepts
---
docs/pages/10-help.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
create mode 100644 docs/pages/10-help.md
(limited to 'docs/pages/10-help.md')
diff --git a/docs/pages/10-help.md b/docs/pages/10-help.md
new file mode 100644
index 0000000..2f3b74f
--- /dev/null
+++ b/docs/pages/10-help.md
@@ -0,0 +1,69 @@
+Help Info
+
+ Adding --help support to commands
+
+
+A CLI without help info is not a good CLI.
+
+In Mingling, use the `#[help]` macro to add help text to commands.
+
+## Simplest Help
+
+Write a help function directly for an Entry:
+
+```rust
+@@@use mingling::macros::help;
+@@@dispatcher!("greet", CMDGreet => EntryGreet);
+#[help]
+fn help_greet(_entry: EntryGreet) {
+ r_println!("Usage: greet [name]");
+ r_println!("Say hello to someone.");
+}
+```
+
+> [!NOTE]
+> Help functions also use `r_println!`, because `#[help]` follows the rendering pipeline — it's a short-circuit render triggered early by the `--help` flag, not logic outside the pipeline.
+
+## Global Help
+
+You can also write help for `ErrorDispatcherNotFound` as the "root help":
+
+```rust
+@@@use mingling::macros::help;
+// Triggered when user passes --help directly
+#[help]
+fn help_root(entry: ErrorDispatcherNotFound) {
+ r_println!("Usage: my-cli ");
+ r_println!("Commands:");
+ r_println!(" greet Say hello");
+}
+```
+
+> [!TIP]
+> `ErrorDispatcherNotFound` is a type generated by `gen_program!()`, representing "no matching command found." Writing `#[help]` for it adds help to the program's root command.
+
+## Requires Setup
+
+For `--help` to work properly, add `BasicProgramSetup` in `main`:
+
+```rust
+@@@use mingling::macros::help;
+@@@use mingling::setup::BasicProgramSetup;
+@@@dispatcher!("greet", CMDGreet => EntryGreet);
+fn main() {
+ let mut program = ThisProgram::new();
+ program.with_setup(BasicProgramSetup);
+ program.with_dispatcher(CMDGreet);
+ program.exec_and_exit();
+}
+```
+
+`BasicProgramSetup` includes `HelpFlagSetup`, which simply sets `program.user_context.help` to `true`.
+
+The actual routing to the `#[help]` function is handled by code generated via `gen_program!()` — it checks this flag during dispatch, and if `true`, goes through the help rendering path, bypassing the Chain.
+
+Without `BasicProgramSetup`, `--help` is treated as a normal argument and passed as input to the Entry's Chain.
+
+
+ Written by @Weicao-CatilGrass
+
--
cgit