From 1f2462ae53446c37c6cfe53a57ea86f695c4ef0a Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Fri, 14 Aug 2026 00:14:30 +0800
Subject: docs: expand trait and type documentation with examples

---
 mingling_core/src/any/group.rs | 81 ++++++++++++++++++++++++++++++------------
 1 file changed, 58 insertions(+), 23 deletions(-)

(limited to 'mingling_core/src/any')

diff --git a/mingling_core/src/any/group.rs b/mingling_core/src/any/group.rs
index 5e5e347..71fe65d 100644
--- a/mingling_core/src/any/group.rs
+++ b/mingling_core/src/any/group.rs
@@ -1,32 +1,67 @@
-use crate::{AnyOutput, ChainProcess, ProgramCollect, Routable};
-
-/// Used to mark a type with a unique enum ID, assisting dynamic dispatch
+/// Member ID for types within a program
+///
+/// This trait provides a member ID for program-internal types, used to determine
+/// the downcast type during dispatch, routing, rendering, and other stages.
 ///
 /// # Safety
 ///
-/// The returned `Group` value is an enum variant created by `register_type!` when
-/// registering the type's ID. Whether the variant matches correctly is guaranteed
-/// by `Grouped derive` or macros like `pack!`. If implemented manually, and the
-/// type name written in `member_id()` does not match the actually registered type,
-/// dispatching to that type will result in **100% undefined behavior**.
+/// This trait is typically provided by the corresponding [`Grouped Derive`](https://docs.rs/mingling/latest/mingling/derive.Grouped.html).
+/// If implemented manually, **make sure** the ID is **exactly identical** to
+/// the name registered by the `register_type!` macro; otherwise, undefined
+/// behavior will inevitably occur when the program routes to that type!
+///
+/// # Manual impl
+///
+/// In general, we recommend using [`#[derive(Grouped)]`](https://docs.rs/mingling/latest/mingling/derive.Grouped.html) to implement it.
+/// However, if you must implement it manually, please follow exactly this pattern:
+///
+/// ```
+/// # use mingling_core::Grouped;
+/// enum ThisProgram {
+///     // Global ID registered by `register_type!`
+///     StateMyType,
+/// }
+///
+/// struct StateMyType;
+///
+/// // SAFETY: This ensures the StateMyType variant during ThisProgram dispatch always corresponds to this type
+/// unsafe impl Grouped<ThisProgram> for StateMyType {
+///     fn member_id() -> ThisProgram {
+///         // must semantically correspond to the type itself!
+///         ThisProgram::StateMyType
+///     }
+/// }
+/// ```
 pub unsafe trait Grouped<Group>
 where
     Self: Sized + 'static,
 {
-    /// Returns the specific enum value representing its ID within that enum
+    /// Get the member ID for this type
+    ///
+    /// # Safety
+    ///
+    /// The returned enum variant must exactly correspond to this type itself,
+    /// i.e., the returned `Group` enum variant must semantically represent this
+    /// type itself. If an incorrect variant is returned, it will cause a type
+    /// casting error and lead to undefined behavior.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use mingling_core::Grouped;
+    /// # enum ThisProgram {
+    /// #     StateMyType,
+    /// # }
+    /// # struct StateMyType;
+    /// # unsafe impl Grouped<ThisProgram> for StateMyType {
+    /// // The following macro registers the type ID
+    /// // mingling::macros::register_type!(StateMyType);
+    ///
+    /// fn member_id() -> ThisProgram {
+    ///     // must semantically correspond to the type itself!
+    ///     ThisProgram::StateMyType
+    /// }
+    /// # }
+    /// ```
     fn member_id() -> Group;
 }
-
-impl<T, C> Routable<C> for T
-where
-    C: ProgramCollect<Enum = C>,
-    T: Grouped<C> + Send,
-{
-    fn to_chain(self) -> ChainProcess<C> {
-        AnyOutput::new(self).route_chain()
-    }
-
-    fn to_render(self) -> ChainProcess<C> {
-        AnyOutput::new(self).route_renderer()
-    }
-}
-- 
cgit