docs: expand trait and type documentation with examples

1 files changed, 42 insertions, 3 deletions

diff --git a/mingling_core/src/asset/help.rs b/mingling_core/src/asset/help.rs
index b3742f2..78da1d1 100644
--- a/mingling_core/src/asset/help.rs
+++ b/mingling_core/src/asset/help.rs
@@ -1,10 +1,49 @@
 use crate::RenderResult;
 
-/// Handles help rendering for command-line arguments
+/// Mingling's program help request.
+///
+/// It provides help capability to a program by binding an entry type. When [`Program`]'s `user_context.help` is `true`,
+/// the first Entry produced by [`Dispatcher`] will be sent into [`HelpRequest`] and rendered into a [`RenderResult`] for the user.
+///
+/// # Manual impl
+///
+/// Normally, [`HelpRequest`] is generated by [`#[help]`](https://docs.rs/mingling/latest/mingling/macros/attr.help.html),
+/// but if you need to implement it manually, please follow the example below:
+///
+/// ```
+/// # use mingling_core::HelpRequest;
+/// # use mingling_core::RenderResult;
+/// # use mingling_core::MockProgramCollect as ThisProgram;
+/// struct GreetHelp;
+/// struct EntryGreet;
+///
+/// impl HelpRequest for GreetHelp {
+///     type Entry = EntryGreet;
+///
+///     fn render_help(p: Self::Entry) -> RenderResult {
+///         let mut result = RenderResult::new();
+///         result.eprintln("USAGE: greet <PARAM...>");
+///         result
+///     }
+/// }
+///
+/// // Register help with the program
+/// // mingling::register_help!(EntryGreet, GreetHelp);
+/// ```
 pub trait HelpRequest {
-    /// The entry type
+    /// The entry type corresponding to this help request.
+    ///
+    /// This associated type indicates which entry the help request will handle. When the program needs to display help,
+    /// the first entry produced by the `Dispatcher` will be passed to the corresponding help request for processing.
     type Entry;
 
-    /// Process the previous value and write the result into the provided [`RenderResult`](./struct.RenderResult.html)
+    /// Render the entry as help information.
+    ///
+    /// This function receives an entry of type [`Self::Entry`] and renders it into a [`RenderResult`].
+    /// Implementors should output help content (such as usage instructions, parameter descriptions, etc.)
+    /// into the [`RenderResult`].
+    ///
+    /// # Return
+    /// Returns a [`RenderResult`] containing the help text, ready to be displayed directly to the user by the caller.
     fn render_help(p: Self::Entry) -> RenderResult;
 }