From 5a23e6b3ad655b15b412720ab81b0508866bebce Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sat, 27 Jun 2026 18:28:52 +0800
Subject: docs: improve documentation, mark internal items as `#[doc(hidden)]`
Add module-level docs for the hook system, enhance doc examples for
macros
with usage syntax, fix typos in cross-references, and hide internal
debugging
macros and mock types from public documentation
---
mingling/src/lib.rs | 63 +++++++++++++++++-----------
mingling_core/src/any.rs | 2 +-
mingling_core/src/any/group.rs | 2 +-
mingling_core/src/debug.rs | 7 ++++
mingling_core/src/program/collection/mock.rs | 1 +
mingling_core/src/program/config.rs | 12 +++++-
mingling_core/src/program/hook.rs | 45 ++++++++++++++++++++
7 files changed, 103 insertions(+), 29 deletions(-)
diff --git a/mingling/src/lib.rs b/mingling/src/lib.rs
index b021479..b4372dc 100644
--- a/mingling/src/lib.rs
+++ b/mingling/src/lib.rs
@@ -47,7 +47,7 @@
//! gen_program!();
//! ```
//!
-// Output:
+//! Output:
//!
//! ```text
//! > mycmd greet
@@ -60,7 +60,10 @@
//!
//! # Examples
//! `Mingling` provides detailed usage examples for your reference.
-//! See [Examples](_mingling_examples/index.html)
+//! See [Examples](_mingling_examples/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/examples.html)
+//!
+//! # About Features
+//! All features of `Mingling` are opt-in. To learn what each feature provides, see [Features](feature/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html#/pages/other/features)
mod example_docs;
@@ -72,46 +75,56 @@ pub use mingling_core as mingling;
#[cfg(feature = "parser")]
pub mod parser;
-/// Re-export from `mingling_macros`
+/// Re-export of all macros from `mingling_macros`.
+///
+/// This module re-exports all macros provided by the `mingling_macros` crate,
+/// including `dispatcher!`, `chain!`, `renderer!`, `gen_program!`, `pack!`,
+/// `r_print!`, `r_println!`, and many others. These macros form the core
+/// building blocks of the Mingling framework.
+///
+/// For detailed documentation, usage examples, and the full list of available
+/// macros, please refer to the `mingling_macros` crate [documentation](https://docs.rs/mingling_macros/latest/mingling_macros/):
+///
+///
#[allow(unused_imports)]
pub mod macros {
- /// Used to generate a struct implementing the `Chain` trait via a method
+ /// `#[chain]` - Used to generate a struct implementing the `Chain` trait via a method
pub use mingling_macros::chain;
- /// Used to generate completion entry
+ /// `#[completion(EntryType)]` - Used to generate completion entry
#[cfg(feature = "comp")]
pub use mingling_macros::completion;
- /// Used to create a dispatcher that routes to a `Chain`
+ /// `dispatcher!("greet", CMDGreet => EntryGreet)` - Used to create a dispatcher that routes to a `Chain`
pub use mingling_macros::dispatcher;
- /// Used to create a dispatcher with clap argument parsing
+ /// `#[dispatcher_clap("greet", CMDGreet)]` - Used to create a dispatcher with clap argument parsing
#[cfg(feature = "clap")]
pub use mingling_macros::dispatcher_clap;
- /// Used to create an empty result value for early return from a chain function
+ /// `empty_result!()` - Used to create an empty result value for early return from a chain function
#[cfg(feature = "extra_macros")]
pub use mingling_macros::empty_result;
- /// Creates a packed entry value from a list of string literals
+ /// `entry!["--greet", "Alice"]` - Creates a packed entry value from a list of string literals
#[cfg(feature = "extra_macros")]
pub use mingling_macros::entry;
- /// Used to collect data and create a command-line context
+ /// `gen_program!()` - Used to collect data and create a command-line context
pub use mingling_macros::gen_program;
- /// Used to register an external type as a group member
+ /// `group!(ErrorIo = std::io::Error)` - Used to register an external type as a group member
#[cfg(feature = "extra_macros")]
pub use mingling_macros::group;
- /// Like `group!` but also marks the type for structured output
+ /// `group_structural!(ErrorIo = std::io::Error)` - Like `group!` but also marks the type for structured output
#[cfg(all(feature = "structural_renderer", feature = "extra_macros"))]
pub use mingling_macros::group_structural;
- /// Used to generate a struct implementing the `HelpRequest` trait via a method
+ /// `#[help]` - Used to generate a struct implementing the `HelpRequest` trait via a method
pub use mingling_macros::help;
- /// Used to create a `Node` struct via a literal
+ /// `node!("remote.rm")` - Used to create a `Node` struct via a literal
pub use mingling_macros::node;
- /// Used to create a wrapper type for use with `Chain` and `Renderer`
+ /// `pack!(StateGreet = String)` - Used to create a wrapper type for use with `Chain` and `Renderer`
pub use mingling_macros::pack;
- /// Like `pack!` but also marks the type for structured output
+ /// `pack_structural!(StateGreet = String)` - Like `pack!` but also marks the type for structured output
#[cfg(feature = "structural_renderer")]
pub use mingling_macros::pack_structural;
- /// Used to create an error struct with automatic `name` field
+ /// `pack_err!(ErrorUnknown)` - Used to create an error struct with automatic `name` field
#[cfg(feature = "extra_macros")]
pub use mingling_macros::pack_err;
- /// Like `pack_err!` but also marks the type for structured output
+ /// `pack_err_structural!(ErrorUnknown)` - Like `pack_err!` but also marks the type for structured output
#[cfg(all(feature = "structural_renderer", feature = "extra_macros"))]
pub use mingling_macros::pack_err_structural;
#[cfg(feature = "comp")]
@@ -121,12 +134,12 @@ pub mod macros {
pub use mingling_macros::program_fallback_gen;
#[doc(hidden)]
pub use mingling_macros::program_final_gen;
- /// Used to generate program setup
+ /// `#[program_setup]` - Used to generate program setup
#[cfg(feature = "extra_macros")]
pub use mingling_macros::program_setup;
- /// Used to print content within a `Renderer` context
+ /// `r_print!("{someting}")` - Used to print content within a `Renderer` context
pub use mingling_macros::r_print;
- /// Used to print content with a newline within a `Renderer` context
+ /// `r_println!("{someting}")` - Used to print content with a newline within a `Renderer` context
pub use mingling_macros::r_println;
#[doc(hidden)]
pub use mingling_macros::register_chain;
@@ -138,16 +151,16 @@ pub mod macros {
pub use mingling_macros::register_renderer;
#[doc(hidden)]
pub use mingling_macros::register_type;
- /// Used to generate a struct implementing the `Renderer` trait via a method
+ /// `#[renderer]` - Used to generate a struct implementing the `Renderer` trait via a method
pub use mingling_macros::renderer;
- /// Used to generate a route that either returns a successful result or early returns an error.
+ /// `route! { /* ... */ }` - Used to generate a route that either returns a successful result or early returns an error.
#[cfg(feature = "extra_macros")]
pub use mingling_macros::route;
+ /// `suggest! { "hello", "bye" }` - Used to generate suggestions
#[cfg(feature = "comp")]
- /// Used to generate suggestions
pub use mingling_macros::suggest;
+ /// `suggest_enum!(EnumNames)` - Used to generate enum suggestions
#[cfg(feature = "comp")]
- /// Used to generate enum suggestions
pub use mingling_macros::suggest_enum;
}
diff --git a/mingling_core/src/any.rs b/mingling_core/src/any.rs
index b115e28..b586f09 100644
--- a/mingling_core/src/any.rs
+++ b/mingling_core/src/any.rs
@@ -12,7 +12,7 @@ pub mod group;
/// Note:
/// - If an enum value that does not belong to this type is incorrectly specified, it will be **unsafely** unwrapped by the scheduler
/// - Structured output via `--json`/`--yaml` is only available for types that implement
-/// [`StructuralData`], which implies `serde::Serialize`.
+/// \[`StructuralData`\], which implies `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 {
diff --git a/mingling_core/src/any/group.rs b/mingling_core/src/any/group.rs
index afe5e3a..cb847d9 100644
--- a/mingling_core/src/any/group.rs
+++ b/mingling_core/src/any/group.rs
@@ -4,7 +4,7 @@ use crate::{AnyOutput, ChainProcess};
///
/// **Note:** Unlike earlier versions, `Groupped` no longer requires `Serialize`
/// even when the `structural_renderer` feature is enabled. Structured output is
-/// controlled separately via the [`StructalData`] trait.
+/// controlled separately via the \[`StructuralData`\] trait.
pub trait Groupped
where
Self: Sized + 'static,
diff --git a/mingling_core/src/debug.rs b/mingling_core/src/debug.rs
index f92cd3d..4865016 100644
--- a/mingling_core/src/debug.rs
+++ b/mingling_core/src/debug.rs
@@ -1,4 +1,5 @@
#[macro_export]
+#[doc(hidden)]
/// A macro that only executes the given expressions when the `debug` feature is enabled.
/// If the feature is not enabled, the expressions are compiled away.
macro_rules! only_debug {
@@ -11,6 +12,7 @@ macro_rules! only_debug {
}
#[macro_export]
+#[doc(hidden)]
/// Logs a message at the trace level, but only if the `debug` feature is enabled.
/// Delegates to `log::trace!` internally.
macro_rules! trace {
@@ -22,6 +24,7 @@ macro_rules! trace {
}
#[macro_export]
+#[doc(hidden)]
/// Logs a message at the debug level, but only if the `debug` feature is enabled.
/// Delegates to `log::debug!` internally.
macro_rules! debug {
@@ -33,6 +36,7 @@ macro_rules! debug {
}
#[macro_export]
+#[doc(hidden)]
/// Logs a message at the info level, but only if the `debug` feature is enabled.
/// Delegates to `log::info!` internally.
macro_rules! info {
@@ -44,6 +48,7 @@ macro_rules! info {
}
#[macro_export]
+#[doc(hidden)]
/// Logs a message at the warn level, but only if the `debug` feature is enabled.
/// Delegates to `log::warn!` internally.
macro_rules! warn {
@@ -55,6 +60,7 @@ macro_rules! warn {
}
#[macro_export]
+#[doc(hidden)]
/// Logs a message at the error level, but only if the `debug` feature is enabled.
/// Delegates to `log::error!` internally.
macro_rules! error {
@@ -66,6 +72,7 @@ macro_rules! error {
}
#[cfg(feature = "debug")]
+#[doc(hidden)]
pub fn init_env_logger() {
let mut log_path = std::env::current_exe()
.expect("Failed to get current executable path")
diff --git a/mingling_core/src/program/collection/mock.rs b/mingling_core/src/program/collection/mock.rs
index b37a709..568000a 100644
--- a/mingling_core/src/program/collection/mock.rs
+++ b/mingling_core/src/program/collection/mock.rs
@@ -17,6 +17,7 @@ use serde::Serialize;
#[cfg_attr(feature = "structural_renderer", derive(Serialize))]
#[allow(unused)]
+#[doc(hidden)]
pub enum MockProgramCollect {
Foo,
Bar,
diff --git a/mingling_core/src/program/config.rs b/mingling_core/src/program/config.rs
index 6d54a4e..c5f91da 100644
--- a/mingling_core/src/program/config.rs
+++ b/mingling_core/src/program/config.rs
@@ -42,13 +42,21 @@ pub struct ProgramStdoutSetting {
pub clap_help_print_behaviour: ClapHelpPrintBehaviour,
}
+/// Behavior when Clap Dispatcher outputs help information
#[cfg(feature = "clap")]
#[derive(Debug, Default, Clone)]
pub enum ClapHelpPrintBehaviour {
- /// Write to RenderResult
+ /// Write help information to `RenderResult` instead of printing to stdout directly.
+ ///
+ /// This allows the help text to be captured and processed as part of the program's
+ /// structured output, which is useful when integrating with external tools or
+ /// when the output needs to be further transformed.
WriteToRenderResult,
- /// Print directly
+ /// Print help information directly to stdout.
+ ///
+ /// This is the default behavior, which prints help text immediately to the terminal
+ /// without any intermediate processing or capture.
#[default]
PrintDirectly,
}
diff --git a/mingling_core/src/program/hook.rs b/mingling_core/src/program/hook.rs
index cd758ca..630baae 100644
--- a/mingling_core/src/program/hook.rs
+++ b/mingling_core/src/program/hook.rs
@@ -1,5 +1,40 @@
#![allow(dead_code)]
+//! Program lifecycle hook system.
+//!
+//! The hook system lets you observe and influence the program's execution
+//! at well-defined lifecycle points — before dispatch, after chain processing,
+//! on finish, etc.
+//!
+//! # Architecture
+//!
+//! Hooks are registered on [`ProgramHook`] via builder methods (`.on_begin()`,
+//! `.on_pre_dispatch()`, `.on_finish()`, …) and attached to the program with
+//! [`Program::with_hook`].
+//!
+//! Each hook callback receives a structured info type (e.g. [`HookPreDispatchInfo`])
+//! and returns either `()` (no-op) or a [`ProgramControlUnit`] / [`ProgramControls`]
+//! to influence the execution flow (override exit code, re-route to another
+//! chain/renderer/help, etc.).
+//!
+//! # Hook Lifecycle Order
+//!
+//! ```text
+//! begin
+//! │
+//! ├─ pre_dispatch ← before an entry is dispatched
+//! ├─ post_dispatch ← after dispatching, before chain
+//! ├─ pre_chain ← before the type enters the chain pipeline
+//! ├─ post_chain ← after chain processing completes
+//! ├─ pre_render ← before the type enters the renderer
+//! ├─ post_render ← after rendering completes
+//! │
+//! finish ← before program exits
+//! ```
+//!
+//! When the `repl` feature is enabled, additional REPL-specific hooks are
+//! available (e.g. `repl_post_readline`, `repl_on_receive_result`).
+
use crate::{Program, ProgramCollect};
mod hook_info;
@@ -8,6 +43,16 @@ pub use hook_info::*;
mod control_unit;
pub use control_unit::*;
+/// The program's lifecycle hook registry.
+///
+/// `ProgramHook` stores optional callbacks for each supported lifecycle
+/// event — from program start (`begin`) through dispatch, chaining, rendering,
+/// and finally program exit (`finish`).
+///
+/// Hooks are constructed via the builder pattern (see methods like
+/// [`on_begin`](Self::on_begin), [`on_pre_dispatch`](Self::on_pre_dispatch),
+/// etc.) and attached to a [`Program`] using
+/// [`Program::with_hook`].
#[derive(Default)]
#[allow(clippy::type_complexity)] // Shutup!
pub struct ProgramHook
--
cgit