From f1ed18e668a830646fe507ee33c4b010a1690342 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Wed, 1 Apr 2026 20:14:56 +0800
Subject: Add documentation for mingling_core

---
 mingling_core/src/any.rs | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

(limited to 'mingling_core/src/any.rs')

diff --git a/mingling_core/src/any.rs b/mingling_core/src/any.rs
index dac0d44..d550ec7 100644
--- a/mingling_core/src/any.rs
+++ b/mingling_core/src/any.rs
@@ -6,8 +6,18 @@ use serde::Serialize;
 use crate::Groupped;
 use crate::error::ChainProcessError;
 
+#[doc(hidden)]
 pub mod group;
 
+/// Any type output
+///
+/// Accepts any type that implements `Send + Groupped<G>`
+/// After being passed into AnyOutput, it will be converted to `Box<dyn Any + Send + 'static>`
+///
+/// Note:
+/// - If an enum value that does not belong to this type is incorrectly specified, it will be **unsafely** unwrapped by the scheduler
+/// - Under the `general_renderer` feature, the passed value must ensure it implements `serde::Serialize`
+/// - It is recommended to use the `pack!` macro from [mingling_macros](https://crates.io/crates/mingling_macros) to create types that can be converted to `AnyOutput`, which guarantees runtime safety
 #[derive(Debug)]
 pub struct AnyOutput<G>
 where
@@ -22,6 +32,7 @@ impl<G> AnyOutput<G>
 where
     G: Display,
 {
+    /// Create an AnyOutput from a `Send + Groupped<G> + Serialize` type
     #[cfg(feature = "general_renderer")]
     pub fn new<T>(value: T) -> Self
     where
@@ -34,6 +45,7 @@ where
         }
     }
 
+    /// Create an AnyOutput from a `Send + Groupped<G>` type
     #[cfg(not(feature = "general_renderer"))]
     pub fn new<T>(value: T) -> Self
     where
@@ -46,6 +58,7 @@ where
         }
     }
 
+    /// Downcast the AnyOutput to a concrete type T
     pub fn downcast<T: 'static>(self) -> Result<T, Self> {
         if self.type_id == std::any::TypeId::of::<T>() {
             Ok(*self.inner.downcast::<T>().unwrap())
@@ -54,6 +67,7 @@ where
         }
     }
 
+    /// Check if the inner value is of type T
     pub fn is<T: 'static>(&self) -> bool {
         self.type_id == std::any::TypeId::of::<T>()
     }
@@ -89,6 +103,12 @@ where
     }
 }
 
+/// Chain exec result type
+///
+/// Stores `Ok` and `Err` types of execution results, used to notify the scheduler what to execute next
+/// - Returns `Ok((`[`AnyOutput`](./struct.AnyOutput.html)`, `[`Next::Chain`](./enum.Next.html)`))` to continue execution with this type next
+/// - Returns `Ok((`[`AnyOutput`](./struct.AnyOutput.html)`, `[`Next::Renderer`](./enum.Next.html)`))` to render this type next and output to the terminal
+/// - Returns `Err(`[`ChainProcessError`](./error/enum.ChainProcessError.html)`]` to terminate the program directly
 pub enum ChainProcess<G>
 where
     G: Display,
@@ -97,6 +117,10 @@ where
     Err(ChainProcessError),
 }
 
+/// Indicates the next step after processing
+///
+/// - `Chain`: Continue execution to the next chain
+/// - `Renderer`: Send output to renderer and end execution
 pub enum Next {
     Chain,
     Renderer,
@@ -106,14 +130,17 @@ impl<G> ChainProcess<G>
 where
     G: Display,
 {
+    /// Returns true if the result is Ok (has a next step)
     pub fn is_next(&self) -> bool {
         matches!(self, Self::Ok(_))
     }
 
+    /// Returns true if the result is an error
     pub fn is_err(&self) -> bool {
         matches!(self, Self::Err(_))
     }
 
+    /// Returns the next step if the result is Ok
     pub fn next(&self) -> Option<&Next> {
         match self {
             Self::Ok((_, next)) => Some(next),
@@ -121,6 +148,7 @@ where
         }
     }
 
+    /// Returns the error if the result is Err
     pub fn err(&self) -> Option<&ChainProcessError> {
         match self {
             Self::Ok(_) => None,
@@ -128,6 +156,7 @@ where
         }
     }
 
+    /// Unwraps the result, panics if it's an error
     pub fn unwrap(self) -> (AnyOutput<G>, Next) {
         match self {
             Self::Ok(tuple) => tuple,
@@ -135,6 +164,7 @@ where
         }
     }
 
+    /// Returns the Ok value or a provided default
     pub fn unwrap_or(self, default: (AnyOutput<G>, Next)) -> (AnyOutput<G>, Next) {
         match self {
             Self::Ok(tuple) => tuple,
@@ -142,6 +172,7 @@ where
         }
     }
 
+    /// Returns the Ok value or computes it from the error
     pub fn unwrap_or_else<F>(self, f: F) -> (AnyOutput<G>, Next)
     where
         F: FnOnce(ChainProcessError) -> (AnyOutput<G>, Next),
-- 
cgit