From db84beb600532f2366babd9a6563214bee1f3732 Mon Sep 17 00:00:00 2001 From: 魏曹先生 <1992414357@qq.com> Date: Mon, 17 Aug 2026 05:51:36 +0800 Subject: docs(sidebar): mark completed issues and reorder them --- docs/dev/_sidebar.md | 8 ++-- docs/dev/pages/issues/_modify-dispatcher-syntax.md | 44 +++++++++++++++++++ docs/dev/pages/issues/_remove-pack-macros.md | 49 ++++++++++++++++++++++ docs/dev/pages/issues/_remove-parser-feature.md | 36 ++++++++++++++++ docs/dev/pages/issues/_remove-with-dispatcher.md | 35 ++++++++++++++++ docs/dev/pages/issues/t0_remove-pack-macros.md | 49 ---------------------- docs/dev/pages/issues/t0_remove-parser-feature.md | 36 ---------------- docs/dev/pages/issues/t0_remove-with-dispatcher.md | 35 ---------------- .../pages/issues/t1_modify-dispatcher-syntax.md | 44 ------------------- 9 files changed, 168 insertions(+), 168 deletions(-) create mode 100644 docs/dev/pages/issues/_modify-dispatcher-syntax.md create mode 100644 docs/dev/pages/issues/_remove-pack-macros.md create mode 100644 docs/dev/pages/issues/_remove-parser-feature.md create mode 100644 docs/dev/pages/issues/_remove-with-dispatcher.md delete mode 100644 docs/dev/pages/issues/t0_remove-pack-macros.md delete mode 100644 docs/dev/pages/issues/t0_remove-parser-feature.md delete mode 100644 docs/dev/pages/issues/t0_remove-with-dispatcher.md delete mode 100644 docs/dev/pages/issues/t1_modify-dispatcher-syntax.md (limited to 'docs/dev') diff --git a/docs/dev/_sidebar.md b/docs/dev/_sidebar.md index cfb482a..e0a77d3 100644 --- a/docs/dev/_sidebar.md +++ b/docs/dev/_sidebar.md @@ -1,15 +1,15 @@ - [Welcome!](README) * ❓ Issues * [[Solved] The Picker2 Arguments Parser](pages/issues/_add-picker2) + * [[T1] Modify the dispatcher! Syntax](pages/issues/_modify-dispatcher-syntax) + * [[T0] Remove the pack! Family of Macros](pages/issues/_remove-pack-macros) + * [[T0] Remove the parser Feature](pages/issues/_remove-parser-feature) * [[Solved] Remove r_print! and r_println! Macros](pages/issues/_remove-r-print-macro) + * [[T0] Remove with_dispatcher and with_dispatchers](pages/issues/_remove-with-dispatcher) * [[Solved] The Command Macro](pages/issues/_the-command-macro) * [[Solved] The Mod Pathfinder](pages/issues/_the-mod-pathfinder) * [[T0] Generalize the REPL System](pages/issues/t0_generalize-repl-system) - * [[T0] Remove the pack! Family of Macros](pages/issues/t0_remove-pack-macros) - * [[T0] Remove the parser Feature](pages/issues/t0_remove-parser-feature) - * [[T0] Remove with_dispatcher and with_dispatchers](pages/issues/t0_remove-with-dispatcher) * [[T1] Higher-Level Abstractions for the Completion System](pages/issues/t1_completion-higher-level-abstractions) - * [[T1] Modify the dispatcher! Syntax](pages/issues/t1_modify-dispatcher-syntax) * [[T1] Move structural_renderer from mingling_core to mingling](pages/issues/t1_move-structural-renderer) * [[T1] The pathf_export Attribute Macro](pages/issues/t1_pathf-export-macro) * [[T2] Automated dispatcher_tree Optimization Decisions](pages/issues/t2_automated-dispatch-tree-optimization) diff --git a/docs/dev/pages/issues/_modify-dispatcher-syntax.md b/docs/dev/pages/issues/_modify-dispatcher-syntax.md new file mode 100644 index 0000000..ed409ef --- /dev/null +++ b/docs/dev/pages/issues/_modify-dispatcher-syntax.md @@ -0,0 +1,44 @@ +

[T1] Modify the dispatcher! Syntax

+

+ Breaking: drop the CMD* struct from the explicit form of dispatcher! +

+ +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0, and it depends on [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher). + +## Background + +Once `Dispatcher` registration is compile-time collected (see [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher)), the `CMD*` struct becomes unnecessary — it only existed to give `with_dispatcher` something to register. + +## Plan + +Simplify the `dispatcher!` syntax: the explicit form no longer creates a `CMD*` struct, so only the entry type needs to be given. + +```rust +// Before +dispatcher!("command", CMDCommand => EntryCommand); + +// After +dispatcher!("command", EntryCommand); + +// NOTE: The implicit mode is not affected +``` + +## Tasks + +- [x] Update `dispatcher!` to accept the simplified explicit form (`"name", EntryType`) +- [x] Decide whether the old `CMDType => EntryType` form should error with a helpful message or be removed outright +- [x] Remove the generated `CMD*` struct machinery +- [x] Update `#[command]` macro internals that depend on `CMD*` +- [x] Migrate examples, tests, and docs +- [x] Keep the implicit mode (`dispatcher!("name")`) working unchanged + +## 🕘 Progress + +- [x] In Progress +- [x] Complete + +

+ Written by @Weicao-CatilGrass +

diff --git a/docs/dev/pages/issues/_remove-pack-macros.md b/docs/dev/pages/issues/_remove-pack-macros.md new file mode 100644 index 0000000..74c21aa --- /dev/null +++ b/docs/dev/pages/issues/_remove-pack-macros.md @@ -0,0 +1,49 @@ +`

[T0] Remove the pack! Family of Macros

+

+ Breaking: retire the entire pack! family in favor of the Grouped derive +

+ +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +Since the very first version of Mingling, the `pack!` macro has been around. Its purpose has gradually narrowed from "creating a type and registering it to Mingling" to "creating a newtype that derives Grouped". In other words, the functionality of `pack!` is gradually being replaced by the `Grouped derive`. + +Furthermore, in 0.2.0, in order to accommodate `StructuralData derive`, Mingling introduced `pack_structural!` and `pack_err_structural!` variants all at once, which greatly increases the maintenance cost of the project. + +## Plan + +Remove the entire `pack!` family of macros (`pack!`, `pack_structural!`, `pack_err_structural!`) as a Breaking Change in 0.5.0. + +All future type creation will be done as follows: + +```rust +// Before +pack!(ResultNames = Vec); + +// After +#[derive(Grouped)] +pub struct ResultNames { + names: Vec +} +``` + +## Tasks + +- [x] Identify all usages of `pack!` / `pack_structural!` / `pack_err_structural!` across the codebase, examples, and docs +- [x] Migrate internal usages to `#[derive(Grouped)]` +- [x] Remove the macro definitions and their re-exports +- [x] Update the docs / helpdoc examples that reference `pack!` +- [x] Update downstream feature docs (`structural_renderer` etc.) where `pack_structural!` was involved +- [x] Verify all tests pass + +## 🕘 Progress + +- [x] In Progress +- [x] Complete + +

+ Written by @Weicao-CatilGrass +

diff --git a/docs/dev/pages/issues/_remove-parser-feature.md b/docs/dev/pages/issues/_remove-parser-feature.md new file mode 100644 index 0000000..c2a11c0 --- /dev/null +++ b/docs/dev/pages/issues/_remove-parser-feature.md @@ -0,0 +1,36 @@ +

[T0] Remove the parser Feature

+

+ Breaking: retire the legacy argument parsing in favor of picker +

+ +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +In 0.3.0, Mingling introduced the `picker` feature, which provides more powerful parameter parsing capabilities. At that point, the original `parser` feature became inadequate. + +The `parser` feature was a temporary argument parsing solution created in the early stages of the project. While it can handle basic argument parsing tasks, its functionality is incomplete and has many limitations (see the [Picker2 issue](_add-picker2) for the full list). + +## Plan + +Completely remove the `parser` feature in 0.5.0. This will directly affect downstream users of the `parser` feature — they must migrate to `picker` (or handle parsing manually). + +## Tasks + +- [x] Identify all usages of the `parser` feature across the codebase, examples, and docs +- [x] Migrate internal usages (tests, examples, dev-dependencies) to `picker` +- [x] Remove the `parser` feature from `mingling` and its dependency (`size`) +- [x] Remove parser-related modules and public API +- [x] Update docs and helpdoc examples +- [x] Note the downstream migration path in the changelog + +## 🕘 Progress + +- [x] In Progress +- [x] Complete + +

+ Written by @Weicao-CatilGrass +

diff --git a/docs/dev/pages/issues/_remove-with-dispatcher.md b/docs/dev/pages/issues/_remove-with-dispatcher.md new file mode 100644 index 0000000..b0d972f --- /dev/null +++ b/docs/dev/pages/issues/_remove-with-dispatcher.md @@ -0,0 +1,35 @@ +

[T0] Remove with_dispatcher and with_dispatchers

+

+ Breaking: make Dispatcher registration compile-time collected in all modes +

+ +> [!NOTE] +> +> This is a **Breaking Change** planned for Mingling 0.5.0. + +## Background + +Mingling's commands must be registered through `with_dispatcher` in order to be usable when `dispatcher_tree` is disabled. This has always been a strange semantic: `chain`, `renderer`, `help`, `completion`, and `metadata` are all collected at compile time, so why is `Dispatcher` the exception? + +In fact, during usage of `dispatcher` from 0.1.0 to 0.4.0, no scenario has ever been encountered where **dynamic registration** was necessary. It is considered unnecessary. + +## Plan + +Make `Dispatcher` registration also compile-time collected in non-`dispatcher_tree` states starting from 0.5.0, and remove `with_dispatcher` / `with_dispatchers` (and the related `#[program_setup]` registration path if it becomes obsolete). + +## Tasks + +- [x] Design how dispatchers are collected at compile time when `dispatcher_tree` is disabled (consistent with how `chain` / `renderer` / `completion` / `metadata` are collected) +- [x] Remove `with_dispatcher` and `with_dispatchers` from the `Program` API +- [x] Update `gen_program!` and the macros so registration happens automatically +- [x] Migrate examples, tests, and docs that call `with_dispatcher` / `with_dispatchers` +- [x] Verify both `dispatcher_tree`-enabled and disabled modes behave identically + +## 🕘 Progress + +- [x] In Progress +- [x] Complete + +

+ Written by @Weicao-CatilGrass +

diff --git a/docs/dev/pages/issues/t0_remove-pack-macros.md b/docs/dev/pages/issues/t0_remove-pack-macros.md deleted file mode 100644 index 517646a..0000000 --- a/docs/dev/pages/issues/t0_remove-pack-macros.md +++ /dev/null @@ -1,49 +0,0 @@ -`

[T0] Remove the pack! Family of Macros

-

- Breaking: retire the entire pack! family in favor of the Grouped derive -

- -> [!NOTE] -> -> This is a **Breaking Change** planned for Mingling 0.5.0. - -## Background - -Since the very first version of Mingling, the `pack!` macro has been around. Its purpose has gradually narrowed from "creating a type and registering it to Mingling" to "creating a newtype that derives Grouped". In other words, the functionality of `pack!` is gradually being replaced by the `Grouped derive`. - -Furthermore, in 0.2.0, in order to accommodate `StructuralData derive`, Mingling introduced `pack_structural!` and `pack_err_structural!` variants all at once, which greatly increases the maintenance cost of the project. - -## Plan - -Remove the entire `pack!` family of macros (`pack!`, `pack_structural!`, `pack_err_structural!`) as a Breaking Change in 0.5.0. - -All future type creation will be done as follows: - -```rust -// Before -pack!(ResultNames = Vec); - -// After -#[derive(Grouped)] -pub struct ResultNames { - names: Vec -} -``` - -## Tasks - -- [ ] Identify all usages of `pack!` / `pack_structural!` / `pack_err_structural!` across the codebase, examples, and docs -- [ ] Migrate internal usages to `#[derive(Grouped)]` -- [ ] Remove the macro definitions and their re-exports -- [ ] Update the docs / helpdoc examples that reference `pack!` -- [ ] Update downstream feature docs (`structural_renderer` etc.) where `pack_structural!` was involved -- [ ] Verify all tests pass - -## 🕘 Progress - -- [ ] In Progress -- [ ] Complete - -

- Written by @Weicao-CatilGrass -

diff --git a/docs/dev/pages/issues/t0_remove-parser-feature.md b/docs/dev/pages/issues/t0_remove-parser-feature.md deleted file mode 100644 index 5c1cffd..0000000 --- a/docs/dev/pages/issues/t0_remove-parser-feature.md +++ /dev/null @@ -1,36 +0,0 @@ -

[T0] Remove the parser Feature

-

- Breaking: retire the legacy argument parsing in favor of picker -

- -> [!NOTE] -> -> This is a **Breaking Change** planned for Mingling 0.5.0. - -## Background - -In 0.3.0, Mingling introduced the `picker` feature, which provides more powerful parameter parsing capabilities. At that point, the original `parser` feature became inadequate. - -The `parser` feature was a temporary argument parsing solution created in the early stages of the project. While it can handle basic argument parsing tasks, its functionality is incomplete and has many limitations (see the [Picker2 issue](_add-picker2) for the full list). - -## Plan - -Completely remove the `parser` feature in 0.5.0. This will directly affect downstream users of the `parser` feature — they must migrate to `picker` (or handle parsing manually). - -## Tasks - -- [ ] Identify all usages of the `parser` feature across the codebase, examples, and docs -- [ ] Migrate internal usages (tests, examples, dev-dependencies) to `picker` -- [ ] Remove the `parser` feature from `mingling` and its dependency (`size`) -- [ ] Remove parser-related modules and public API -- [ ] Update docs and helpdoc examples -- [ ] Note the downstream migration path in the changelog - -## 🕘 Progress - -- [ ] In Progress -- [ ] Complete - -

- Written by @Weicao-CatilGrass -

diff --git a/docs/dev/pages/issues/t0_remove-with-dispatcher.md b/docs/dev/pages/issues/t0_remove-with-dispatcher.md deleted file mode 100644 index 8779d74..0000000 --- a/docs/dev/pages/issues/t0_remove-with-dispatcher.md +++ /dev/null @@ -1,35 +0,0 @@ -

[T0] Remove with_dispatcher and with_dispatchers

-

- Breaking: make Dispatcher registration compile-time collected in all modes -

- -> [!NOTE] -> -> This is a **Breaking Change** planned for Mingling 0.5.0. - -## Background - -Mingling's commands must be registered through `with_dispatcher` in order to be usable when `dispatcher_tree` is disabled. This has always been a strange semantic: `chain`, `renderer`, `help`, `completion`, and `metadata` are all collected at compile time, so why is `Dispatcher` the exception? - -In fact, during usage of `dispatcher` from 0.1.0 to 0.4.0, no scenario has ever been encountered where **dynamic registration** was necessary. It is considered unnecessary. - -## Plan - -Make `Dispatcher` registration also compile-time collected in non-`dispatcher_tree` states starting from 0.5.0, and remove `with_dispatcher` / `with_dispatchers` (and the related `#[program_setup]` registration path if it becomes obsolete). - -## Tasks - -- [ ] Design how dispatchers are collected at compile time when `dispatcher_tree` is disabled (consistent with how `chain` / `renderer` / `completion` / `metadata` are collected) -- [ ] Remove `with_dispatcher` and `with_dispatchers` from the `Program` API -- [ ] Update `gen_program!` and the macros so registration happens automatically -- [ ] Migrate examples, tests, and docs that call `with_dispatcher` / `with_dispatchers` -- [ ] Verify both `dispatcher_tree`-enabled and disabled modes behave identically - -## 🕘 Progress - -- [ ] In Progress -- [ ] Complete - -

- Written by @Weicao-CatilGrass -

diff --git a/docs/dev/pages/issues/t1_modify-dispatcher-syntax.md b/docs/dev/pages/issues/t1_modify-dispatcher-syntax.md deleted file mode 100644 index f1a9346..0000000 --- a/docs/dev/pages/issues/t1_modify-dispatcher-syntax.md +++ /dev/null @@ -1,44 +0,0 @@ -

[T1] Modify the dispatcher! Syntax

-

- Breaking: drop the CMD* struct from the explicit form of dispatcher! -

- -> [!NOTE] -> -> This is a **Breaking Change** planned for Mingling 0.5.0, and it depends on [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher). - -## Background - -Once `Dispatcher` registration is compile-time collected (see [Remove with_dispatcher and with_dispatchers](t0_remove-with-dispatcher)), the `CMD*` struct becomes unnecessary — it only existed to give `with_dispatcher` something to register. - -## Plan - -Simplify the `dispatcher!` syntax: the explicit form no longer creates a `CMD*` struct, so only the entry type needs to be given. - -```rust -// Before -dispatcher!("command", CMDCommand => EntryCommand); - -// After -dispatcher!("command", EntryCommand); - -// NOTE: The implicit mode is not affected -``` - -## Tasks - -- [ ] Update `dispatcher!` to accept the simplified explicit form (`"name", EntryType`) -- [ ] Decide whether the old `CMDType => EntryType` form should error with a helpful message or be removed outright -- [ ] Remove the generated `CMD*` struct machinery -- [ ] Update `#[command]` macro internals that depend on `CMD*` -- [ ] Migrate examples, tests, and docs -- [ ] Keep the implicit mode (`dispatcher!("name")`) working unchanged - -## 🕘 Progress - -- [ ] In Progress -- [ ] Complete - -

- Written by @Weicao-CatilGrass -

-- cgit