use crate::RenderResult;

/// Mingling's program help request.
///
/// It provides help capability to a program by binding an entry type. When [`Program`](https://docs.rs/mingling/latest/mingling/struct.Program.html)'s `user_context.help` is `true`,
/// the first Entry produced by [`Dispatcher`](https://docs.rs/mingling/latest/mingling/trait.Dispatcher.html) 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 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;

    /// 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;
}