From 9b8deaeced4f4a6f7c2492528019cc6e10c379ac Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Thu, 9 Jul 2026 20:32:59 +0800
Subject: docs: restructure dev-docs sidebar and move pages into subdirectories

---
 docs/dev-docs/pages/issues/.name                 |  1 +
 docs/dev-docs/pages/issues/the-mod-pathfinder.md | 64 +++++++++++++++++
 docs/dev-docs/pages/issues/the-shit-time.md      | 90 ++++++++++++++++++++++++
 3 files changed, 155 insertions(+)
 create mode 100644 docs/dev-docs/pages/issues/.name
 create mode 100644 docs/dev-docs/pages/issues/the-mod-pathfinder.md
 create mode 100644 docs/dev-docs/pages/issues/the-shit-time.md

(limited to 'docs/dev-docs/pages/issues')

diff --git a/docs/dev-docs/pages/issues/.name b/docs/dev-docs/pages/issues/.name
new file mode 100644
index 0000000..f99478d
--- /dev/null
+++ b/docs/dev-docs/pages/issues/.name
@@ -0,0 +1 @@
+Issues
diff --git a/docs/dev-docs/pages/issues/the-mod-pathfinder.md b/docs/dev-docs/pages/issues/the-mod-pathfinder.md
new file mode 100644
index 0000000..5f8c902
--- /dev/null
+++ b/docs/dev-docs/pages/issues/the-mod-pathfinder.md
@@ -0,0 +1,64 @@
+<h1 align="center">The Mod Pathfinder</h1>
+<p align="center">
+    A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros.
+</p>
+
+## Background
+
+Currently, `gen_program!` requires all involved types to be `use`d within their module. Mingling lacks a complete module path analyzer — waiting for `proc-macro-span` to stabilize is clearly not practical, so a solution for obtaining module paths is needed.
+
+## Solution
+
+We plan to create an analyzer called `mingling-mod-pathf`, enabled via Mingling's `"pathf"` feature, to compute the full paths of all defined Mingling types.
+
+### Behavior When Enabled
+
+**`mingling_core`**: If the `builds` feature is enabled, introduces the `mingling::build::analyze_and_build_type_mapping()` method (analysis completed at Build-Time)
+
+**`mingling_macros`**: Modifies the behavior of the `gen_program!()` macro — automatically loads the mapping table from the analysis file generated by `mingling::build::analyze_and_build_type_mapping()`, and directly uses the full `mod::path` instead of `TypeName` (injected at Compile-Time)
+
+## Challenges
+
+`mingling-mod-pathf` needs to understand **all** Mingling syntax features.
+Fortunately, Mingling's type creation is almost always explicit:
+
+```rust
+mod sub {
+    mingling::macros::pack!(ResultMyName = String); // directly creates ..::sub::ResultMyName
+}
+```
+
+There are a few exceptions, such as the implicit Dispatcher provided by `extra_macros`, but these can be inferred from the node name:
+
+```rust
+dispatcher!("remote.add"); // although the type is unknown, we can infer CMDRemoteAdd and EntryRemoteAdd
+```
+
+And also `#[program_setup]`:
+
+```rust
+#[program_setup] // can infer CustomSetup from the function name `custom_setup`
+fn custom_setup(program: &mut Program<ThisProgram>) {
+    program.with_dispatchers((CMD1, CMD2, CMD3, CMD4, CMD5));
+}
+```
+
+## Pathf Output Format
+
+Uses TOML key-value pairs, formatted as follows:
+
+```toml
+ResultRemoteAdd = "crate::mymod::ResultRemoteAdd"
+```
+
+Recommended storage location is under the target directory:
+
+```
+/target/{target}/{crate-name}/type-mapping.toml
+```
+
+## Other Issues
+
+This solution is limited to Mingling's own syntax system. If types like `dispatcher!`, `pack!` are indirectly expanded through macros, the analyzer will not be able to discover them.
+
+However, this approach solves the current main pain points, so this issue can be set aside for now and addressed later.
diff --git a/docs/dev-docs/pages/issues/the-shit-time.md b/docs/dev-docs/pages/issues/the-shit-time.md
new file mode 100644
index 0000000..77a8af9
--- /dev/null
+++ b/docs/dev-docs/pages/issues/the-shit-time.md
@@ -0,0 +1,90 @@
+<h1 align="center">Some Situations Where You'd Be Like "Shit!"</h1>
+<p align="center">
+    This document collects the discomforts currently experienced while using Mingling.
+</p>
+
+This document collects the discomforts currently experienced while using Mingling.
+
+Of course, you can also contribute to this document.
+
+---
+
+## Why is there no fallback completion logic?
+
+(completion) (fallback)
+
+Currently, Mingling's Completion only supports providing completion logic for specific subcommands, with no way to provide global completion.
+
+For example:
+
+```
+mycmd <tab>
+completion:
+--help    -h  --- Display helps
+--version -V  --- Display versions
+```
+
+Currently, there is no workaround.
+
+Ideal solution:
+
+```rust
+#[completion(EntryGlobal)]
+fn complete(ctx: &ShellContext) -> Suggest {
+    // ...
+}
+```
+
+---
+
+## Why can't I register descriptions for commands?
+
+(completion) (dispatcher)
+
+Currently, Mingling's Completion cannot register a description for each subcommand.
+
+For example:
+
+```
+mycmd <tab>
+completion:
+add rm list <--- You cannot register descriptions for commands
+```
+
+Expected behavior:
+
+```
+mycmd <tab>
+completion:
+add  --- Add something
+rm   --- Remove something
+list --- List something
+```
+
+Ideal solution:
+
+```rust
+// It should be able to freely integrate with crates that provide i18n functionality,
+// so the following approach cannot be used as a data source for descriptions.
+dispatcher! {
+    /// Add Something <--- How to i18n?
+    "add", CMDAdd => EntryAdd
+}
+
+// Ideally, it should satisfy the following two conditions:
+// 1. No need to use `with_dispatcher`, because `with_dispatcher` is disabled in `dispatch_tree` mode
+// 2. Must be able to accept String or &str at runtime
+
+// Current idea
+#[inline(always)]
+#[dispatcher_desc(EntryAdd)]
+fn desc_add() -> String {
+    // If using rust_i18n
+    t!("cmd.add.desc")
+}
+
+// Collected and generated by `gen_program!()`
+// Generate something like get_dispatcher_desc(id: &ThisProgram) -> String
+// Match the corresponding function using enum values inside ThisProgram
+gen_program!()
+```
-- 
cgit