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/concepts/4-program-collect.md | 52 ++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 docs/pages/concepts/4-program-collect.md

(limited to 'docs/pages/concepts/4-program-collect.md')

diff --git a/docs/pages/concepts/4-program-collect.md b/docs/pages/concepts/4-program-collect.md
new file mode 100644
index 0000000..a24f115
--- /dev/null
+++ b/docs/pages/concepts/4-program-collect.md
@@ -0,0 +1,52 @@
+<h1 align="center">About ProgramCollect</h1>
+<p align="center">
+    Understand how gen_program!() builds a program
+</p>
+
+Every Mingling program ends with a `gen_program!()` call. Behind the scenes, it does three things to scaffold the entire program.
+
+## The three tasks of gen_program!()
+
+### 1. Generate an enum
+
+Scans the current module for all types marked with `pack!`, `#[chain]`, `#[renderer]` and similar macros, then generates an enum variant for each type.
+
+This enum is the type of `G` in `AnyOutput<G>` — the scheduler uses enum variants to distinguish different data flowing through the pipeline.
+
+### 2. Generate a ProgramCollect impl
+
+`ProgramCollect` is a trait that defines the mapping of **"which type each enum variant corresponds to and who handles it"**:
+
+- **`do_chain`** — calls the corresponding `#[chain]` function by `member_id`, returns a new `AnyOutput` and `NextProcess`
+- **`render`** — calls the corresponding `#[renderer]` function by `member_id`, writes to `RenderResult`
+- **`render_help`** — calls the corresponding `#[help]` function by `member_id`
+- **`has_chain` / `has_renderer`** — checks whether a variant has a corresponding handler
+- **`build_dispatcher_not_found` / `build_renderer_not_found` / `build_empty_result`** — three built-in fallback types for edge cases
+
+This mapping is resolved at runtime via enum matching — only the enum and match branches are generated at compile time; actual function calls happen at runtime.
+
+### 3. Generate ThisProgram
+
+Generates the `ThisProgram` type alias, pointing to `Program<GeneratedEnum>`. That's why you can write `ThisProgram::new()` directly in `main` — it's the complete type of your whole program.
+
+---
+
+## Differences under `pathf` and `dispatch_tree`
+
+The above describes the default behavior, which changes when specific features are enabled:
+
+### 1. `dispatch_tree` feature
+
+The Dispatcher no longer uses `Vec<Box<dyn Dispatcher>>` for linear matching. Instead, the subcommand structure is built as a prefix tree (Trie) at compile time.
+
+Matching complexity drops from `O(n)` to `O(k)` — where `k` is input length, independent of the number of commands.
+
+### 2. `pathf` feature (Module Pathfinder)
+
+By default, all macro-marked types must be in the same module for `gen_program!()` to collect them.
+
+With `pathf` enabled, the compiler automatically scans all sub-modules at compile time, finds all macro-marked types, and generates full module path references — types defined in deep sub-modules don't need a manual `use`.
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>
-- 
cgit