From 86bc9000c5687db6434a5d20f409dda8b1d7a43a Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sun, 28 Jun 2026 09:18:17 +0800
Subject: feat(docs): add Module Pathfinder example for the `pathf` feature

---
 docs/example-pages/examples.json           | 18 +++++++
 examples/example-pathfinder/Cargo.lock     | 85 ++++++++++++++++++++++++++++++
 examples/example-pathfinder/Cargo.toml     | 25 +++++++++
 examples/example-pathfinder/build.rs       | 10 ++++
 examples/example-pathfinder/page.toml      | 10 ++++
 examples/example-pathfinder/src/main.rs    | 30 +++++++++++
 examples/example-pathfinder/src/sub/mod.rs | 21 ++++++++
 examples/test-examples.toml                | 10 ++++
 mingling/src/example_docs.rs               | 63 ++++++++++++++++++++++
 9 files changed, 272 insertions(+)
 create mode 100644 examples/example-pathfinder/Cargo.lock
 create mode 100644 examples/example-pathfinder/Cargo.toml
 create mode 100644 examples/example-pathfinder/build.rs
 create mode 100644 examples/example-pathfinder/page.toml
 create mode 100644 examples/example-pathfinder/src/main.rs
 create mode 100644 examples/example-pathfinder/src/sub/mod.rs

diff --git a/docs/example-pages/examples.json b/docs/example-pages/examples.json
index f3484f3..a9af210 100644
--- a/docs/example-pages/examples.json
+++ b/docs/example-pages/examples.json
@@ -249,6 +249,24 @@
       "Cargo.toml"
     ]
   },
+  {
+    "id": "example-pathfinder",
+    "name": "Module Pathfinder",
+    "icon": "🧭",
+    "category": "advanced",
+    "desc": "Demonstrates the `pathf` feature, which automatically resolves type module paths at build time. Types can be defined in submodules without explicit `use` in the main module.\n",
+    "tags": [
+      "pathf",
+      "build.rs",
+      "architecture"
+    ],
+    "files": [
+      "Cargo.toml",
+      "build.rs",
+      "src/main.rs",
+      "src/sub/mod.rs"
+    ]
+  },
   {
     "id": "example-repl-basic",
     "name": "REPL Basic",
diff --git a/examples/example-pathfinder/Cargo.lock b/examples/example-pathfinder/Cargo.lock
new file mode 100644
index 0000000..92af163
--- /dev/null
+++ b/examples/example-pathfinder/Cargo.lock
@@ -0,0 +1,85 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "example-pathfinder"
+version = "0.1.0"
+dependencies = [
+ "mingling",
+]
+
+[[package]]
+name = "just_fmt"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5454cda0d57db59778608d7a47bff5b16c6705598265869fb052b657f66cf05e"
+
+[[package]]
+name = "mingling"
+version = "0.2.0"
+dependencies = [
+ "mingling_core",
+ "mingling_macros",
+]
+
+[[package]]
+name = "mingling_core"
+version = "0.2.0"
+dependencies = [
+ "just_fmt",
+ "mingling_pathf",
+]
+
+[[package]]
+name = "mingling_macros"
+version = "0.2.0"
+dependencies = [
+ "just_fmt",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "mingling_pathf"
+version = "0.2.0"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
diff --git a/examples/example-pathfinder/Cargo.toml b/examples/example-pathfinder/Cargo.toml
new file mode 100644
index 0000000..bd362f2
--- /dev/null
+++ b/examples/example-pathfinder/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "example-pathfinder"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies.mingling]
+path = "../../mingling"
+
+features = [
+    # Enable `pathf` features
+    "pathf",
+]
+
+[build-dependencies.mingling]
+path = "../../mingling"
+
+features = [
+    # Enable `pathf` features
+    "pathf",
+
+    # Enable the `builds` feature for build-time support
+    "builds",
+]
+
+[workspace]
diff --git a/examples/example-pathfinder/build.rs b/examples/example-pathfinder/build.rs
new file mode 100644
index 0000000..1dcc2fc
--- /dev/null
+++ b/examples/example-pathfinder/build.rs
@@ -0,0 +1,10 @@
+use mingling::builds::analyze_and_build_type_mapping;
+
+fn main() {
+    // --------- IMPORTANT ---------
+    // Use this method in build.rs,
+    //   to analyze the project structure at build time,
+    //   and automatically introduce members from other modules into gen_program!()
+    analyze_and_build_type_mapping().unwrap();
+    // --------- IMPORTANT ---------
+}
diff --git a/examples/example-pathfinder/page.toml b/examples/example-pathfinder/page.toml
new file mode 100644
index 0000000..54f4118
--- /dev/null
+++ b/examples/example-pathfinder/page.toml
@@ -0,0 +1,10 @@
+[example]
+id = "example-pathfinder"
+name = "Module Pathfinder"
+icon = "🧭"
+category = "advanced"
+desc = """
+Demonstrates the `pathf` feature, which automatically resolves type module paths at build time. Types can be defined in submodules without explicit `use` in the main module.
+"""
+tags = ["pathf", "build.rs", "architecture"]
+files = [ "Cargo.toml", "build.rs", "src/main.rs", "src/sub/mod.rs"]
diff --git a/examples/example-pathfinder/src/main.rs b/examples/example-pathfinder/src/main.rs
new file mode 100644
index 0000000..0f93a8d
--- /dev/null
+++ b/examples/example-pathfinder/src/main.rs
@@ -0,0 +1,30 @@
+//! Example: Module Pathfinder (pathf)
+//!
+//! > This example demonstrates how to use the `pathf` feature to define types
+//! > in submodules without needing explicit `use` in the main module.
+//! > All type paths are resolved automatically at build time.
+//!
+//! Run:
+//! ```bash
+//! cargo run --manifest-path examples/example-pathfinder/Cargo.toml --quiet -- greet
+//! cargo run --manifest-path examples/example-pathfinder/Cargo.toml --quiet -- greet Alice
+//! ```
+//!
+//! Output:
+//! ```plaintext
+//! Hello, World!
+//! Hello, Alice!
+//! ```
+
+mod sub;
+
+use mingling::macros::gen_program;
+use crate::sub::CMDGreet;
+
+fn main() {
+    let mut program = ThisProgram::new();
+    program.with_dispatcher(CMDGreet);
+    program.exec_and_exit();
+}
+
+gen_program!();
diff --git a/examples/example-pathfinder/src/sub/mod.rs b/examples/example-pathfinder/src/sub/mod.rs
new file mode 100644
index 0000000..ef10a75
--- /dev/null
+++ b/examples/example-pathfinder/src/sub/mod.rs
@@ -0,0 +1,21 @@
+use mingling::prelude::*;
+use crate::Next;
+
+dispatcher!("greet", CMDGreet => EntryGreet);
+pack!(ResultName = String);
+
+#[chain]
+pub fn handle_greet(args: EntryGreet) -> Next {
+    let name: ResultName = args
+        .inner
+        .first()
+        .cloned()
+        .unwrap_or_else(|| "World".to_string())
+        .into();
+    name
+}
+
+#[renderer]
+pub fn render_name(name: ResultName) {
+    r_println!("Hello, {}!", *name);
+}
diff --git a/examples/test-examples.toml b/examples/test-examples.toml
index b4cbb6d..e1a23c2 100644
--- a/examples/test-examples.toml
+++ b/examples/test-examples.toml
@@ -257,3 +257,13 @@ expect.result = '{"name":"error_not_dir_structural","info":"Cargo.toml"}'
 command = "find-structural examples --json"
 expect.exit-code = 0
 expect.result = '{"inner":"examples"}'
+
+[[test.example-pathfinder]]
+command = "greet"
+expect.exit-code = 0
+expect.result = "Hello, World!"
+
+[[test.example-pathfinder]]
+command = "greet Alice"
+expect.exit-code = 0
+expect.result = "Hello, Alice!"
diff --git a/mingling/src/example_docs.rs b/mingling/src/example_docs.rs
index 5208077..2d2e61c 100644
--- a/mingling/src/example_docs.rs
+++ b/mingling/src/example_docs.rs
@@ -1831,6 +1831,69 @@ pub mod example_pack_err {}
 /// gen_program!();
 /// ```
 pub mod example_panic_unwind {}
+/// Example: Module Pathfinder (pathf)
+///
+///  > This example demonstrates how to use the `pathf` feature to define types
+///  > in submodules without needing explicit `use` in the main module.
+///  > All type paths are resolved automatically at build time.
+///
+///  Run:
+///  ```bash
+///  cargo run --manifest-path examples/example-pathfinder/Cargo.toml --quiet -- greet
+///  cargo run --manifest-path examples/example-pathfinder/Cargo.toml --quiet -- greet Alice
+///  ```
+///
+///  Output:
+///  ```plaintext
+///  Hello, World!
+///  Hello, Alice!
+///  ```
+///
+/// Source code (./Cargo.toml)
+/// ```toml
+/// [package]
+/// name = "example-pathfinder"
+/// version = "0.1.0"
+/// edition = "2024"
+///
+/// [dependencies.mingling]
+/// path = "../../mingling"
+///
+/// features = [
+///     # Enable `pathf` features
+///     "pathf",
+/// ]
+///
+/// [build-dependencies.mingling]
+/// path = "../../mingling"
+///
+/// features = [
+///     # Enable `pathf` features
+///     "pathf",
+///
+///     # Enable the `builds` feature for build-time support
+///     "builds",
+/// ]
+///
+/// [workspace]
+/// ```
+///
+/// Source code (./src/main.rs)
+/// ```ignore
+/// mod sub;
+///
+/// use mingling::macros::gen_program;
+/// use crate::sub::CMDGreet;
+///
+/// fn main() {
+///     let mut program = ThisProgram::new();
+///     program.with_dispatcher(CMDGreet);
+///     program.exec_and_exit();
+/// }
+///
+/// gen_program!();
+/// ```
+pub mod example_pathfinder {}
 /// Example REPL Basic
 ///
 ///  > This example demonstrates how to develop a REPL program using the `repl` feature
-- 
cgit