aboutsummaryrefslogtreecommitdiff
path: root/docs/_zh_CN/pages/10-help.md
diff options
context:
space:
mode:
author魏曹先生 <1992414357@qq.com>2026-06-30 18:05:05 +0800
committer魏曹先生 <1992414357@qq.com>2026-06-30 18:05:05 +0800
commit13408e79b940e9a33ca593ed30d1b20c54e01234 (patch)
tree282549991a3f31791401ca2f3255b9318679d2e9 /docs/_zh_CN/pages/10-help.md
parent29867ab5c0b40378a33318d989c809f90fc7d3aa (diff)
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
Diffstat (limited to 'docs/_zh_CN/pages/10-help.md')
-rw-r--r--docs/_zh_CN/pages/10-help.md69
1 files changed, 69 insertions, 0 deletions
diff --git a/docs/_zh_CN/pages/10-help.md b/docs/_zh_CN/pages/10-help.md
new file mode 100644
index 0000000..7b56557
--- /dev/null
+++ b/docs/_zh_CN/pages/10-help.md
@@ -0,0 +1,69 @@
+<h1 align="center">帮助信息</h1>
+<p align="center">
+ 为命令添加 --help 支持
+</p>
+
+没有帮助信息的 CLI 不是好 CLI。
+
+Mingling 里用 `#[help]` 宏给命令添加帮助文本。
+
+## 最简单的帮助
+
+直接给 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]
+> 帮助函数里也用 `r_println!`,因为 `#[help]` 走的也是渲染流程 —— 它是被 `--help` 参数提前触发的短路渲染,不是独立于管线之外的逻辑。
+
+## 全局帮助
+
+你也可以为 `ErrorDispatcherNotFound` 写帮助,作为"根帮助":
+
+```rust
+@@@use mingling::macros::help;
+// 用户直接输入 --help 时触发
+#[help]
+fn help_root(entry: ErrorDispatcherNotFound) {
+ r_println!("Usage: my-cli <command>");
+ r_println!("Commands:");
+ r_println!(" greet Say hello");
+}
+```
+
+> [!TIP]
+> `ErrorDispatcherNotFound` 是 `gen_program!()` 自动生成的类型,代表"没有匹配到任何命令"的情况。为它写 `#[help]` 就是给程序的根命令加帮助。
+
+## 需要 Setup 配合
+
+要让 `--help` 正常工作,需要在 `main` 里加上 `BasicProgramSetup`:
+
+```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` 内置了 `HelpFlagSetup`,它的作用仅仅是把 `program.user_context.help` 设为 `true`。
+
+真正把请求路由到 `#[help]` 函数的是 `gen_program!()` 生成的代码 —— 它在调度时检查这个标记,如果为 `true` 就走帮助渲染路径,不经过 Chain。
+
+不加 `BasicProgramSetup` 的话,`--help` 只是一个普通参数,会被当成 Entry 的输入传给 Chain。
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+ Written by @Weicao-CatilGrass
+</p>