diff --git a/mingling/Cargo.toml b/mingling/Cargo.toml
index 45bbaa1..61a6c2b 100644
--- a/mingling/Cargo.toml
+++ b/mingling/Cargo.toml
@@ -5,7 +5,7 @@ edition = "2024"
authors = ["Weicao-CatilGrass"]
license = "MIT OR Apache-2.0"
readme = "README.md"
-description = "Rust CLI framework for many subcmds & complex workflows, reduces boilerplate via proc macros, focus on biz logic"
+description = "A Rust CLI framework for many subcmds & complex workflows, reduces boilerplate via proc macros, focus on biz logic"
keywords = ["cli", "framework", "procedural", "subcommand", "command-line"]
categories = ["command-line-interface"]
repository = "https://github.com/catilgrass/mingling"
@@ -15,12 +15,15 @@ serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
mingling = { path = ".", features = ["comp", "general_renderer", "parser"] }
+[package.metadata.docs.rs]
+features = ["general_renderer", "repl", "comp", "parser"]
+
[features]
nightly = ["mingling_core/nightly", "mingling_macros/nightly"]
debug = ["mingling_core/debug"]
async = ["mingling_core/async", "mingling_macros/async"]
-default = ["mingling_core/default"]
+default = ["mingling_core/default", "mingling_macros/default"]
clap = ["mingling_core/clap", "mingling_macros/clap"]
general_renderer = [
diff --git a/mingling/src/lib.rs b/mingling/src/lib.rs
index ed168ff..fa81f76 100644
--- a/mingling/src/lib.rs
+++ b/mingling/src/lib.rs
@@ -1,7 +1,7 @@
//! Mingling
//!
//! # Intro
-//! `Mingling` is a Rust command-line framework. Its name comes from the Chinese Pinyin for "命令", which means "Command".
+//! A Rust CLI framework for many subcmds & complex workflows, reduces boilerplate via proc macros, focus on biz logic
//!
//! # Use
//!
@@ -51,10 +51,12 @@
//! ```
//!
//! # Features
+//! - `async` enables async runtime support for command execution, see [example](_mingling_examples/example_async/index.html) for details
//! - `comp` enables command completion functionality, see [example](_mingling_examples/example_completion/index.html) for details
//! - `parser` enables the `mingling::parser` module, see [example](_mingling_examples/example_picker/index.html) for details
//! - `general_renderer` adds support for serialized output formats such as JSON and YAML, see [example](_mingling_examples/example_general_renderer/index.html) for details
//!
+//!
//! # Examples
//! `Mingling` provides detailed usage examples for your reference.
//! See [Examples](_mingling_examples/index.html)
diff --git a/mingling_core/src/asset/comp.rs b/mingling_core/src/asset/comp.rs
index c1c7ab5..a6299e1 100644
--- a/mingling_core/src/asset/comp.rs
+++ b/mingling_core/src/asset/comp.rs
@@ -33,6 +33,11 @@ pub trait CompletionEntry {
fn get_input(self) -> Vec(ctx: &ShellContext) -> Suggest
diff --git a/mingling_core/src/asset/comp/flags.rs b/mingling_core/src/asset/comp/flags.rs
index f61e9ac..452126b 100644
--- a/mingling_core/src/asset/comp/flags.rs
+++ b/mingling_core/src/asset/comp/flags.rs
@@ -1,13 +1,22 @@
use just_fmt::snake_case;
+/// Represents the shell environment for which the output format is intended.
+///
+/// This enum defines the supported shell types that can be used for
+/// generating shell-specific command syntax, scripts, or completions.
#[derive(Default, Debug, Clone)]
#[cfg_attr(feature = "general_renderer", derive(serde::Serialize))]
pub enum ShellFlag {
+ /// Represents the Bash shell.
#[default]
Bash,
+ /// Represents the Zsh shell.
Zsh,
+ /// Represents the Fish shell.
Fish,
+ /// Represents PowerShell.
Powershell,
+ /// A custom or unsupported shell type, identified by the provided string.
Other(String),
}
diff --git a/mingling_core/src/asset/comp/suggest.rs b/mingling_core/src/asset/comp/suggest.rs
index 62844a7..6d64341 100644
--- a/mingling_core/src/asset/comp/suggest.rs
+++ b/mingling_core/src/asset/comp/suggest.rs
@@ -66,10 +66,20 @@ impl std::ops::DerefMut for Suggest {
}
}
+/// Represents a single suggestion item for shell completion.
+///
+/// This enum has two variants:
+/// - `Simple(String)`: A suggestion without any description.
+/// - `WithDescription(String, String)`: A suggestion with an associated description.
+///
+/// The first `String` always holds the suggestion text, and the second `String` (if present)
+/// holds an optional description providing additional context.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "general_renderer", derive(serde::Serialize))]
pub enum SuggestItem {
+ /// A simple suggestion with only the suggestion text.
Simple(String),
+ /// A suggestion with both text and a description.
WithDescription(String, String),
}
diff --git a/mingling_core/src/debug.rs b/mingling_core/src/debug.rs
index 9fd553c..f92cd3d 100644
--- a/mingling_core/src/debug.rs
+++ b/mingling_core/src/debug.rs
@@ -1,4 +1,6 @@
#[macro_export]
+/// 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 {
($($expr:expr);* $(;)?) => {
#[cfg(feature = "debug")]
@@ -9,6 +11,8 @@ macro_rules! only_debug {
}
#[macro_export]
+/// Logs a message at the trace level, but only if the `debug` feature is enabled.
+/// Delegates to `log::trace!` internally.
macro_rules! trace {
($($arg:tt)*) => {
$crate::only_debug! {
@@ -18,6 +22,8 @@ macro_rules! trace {
}
#[macro_export]
+/// Logs a message at the debug level, but only if the `debug` feature is enabled.
+/// Delegates to `log::debug!` internally.
macro_rules! debug {
($($arg:tt)*) => {
$crate::only_debug! {
@@ -27,6 +33,8 @@ macro_rules! debug {
}
#[macro_export]
+/// Logs a message at the info level, but only if the `debug` feature is enabled.
+/// Delegates to `log::info!` internally.
macro_rules! info {
($($arg:tt)*) => {
$crate::only_debug! {
@@ -36,6 +44,8 @@ macro_rules! info {
}
#[macro_export]
+/// Logs a message at the warn level, but only if the `debug` feature is enabled.
+/// Delegates to `log::warn!` internally.
macro_rules! warn {
($($arg:tt)*) => {
$crate::only_debug! {
@@ -45,6 +55,8 @@ macro_rules! warn {
}
#[macro_export]
+/// Logs a message at the error level, but only if the `debug` feature is enabled.
+/// Delegates to `log::error!` internally.
macro_rules! error {
($($arg:tt)*) => {
$crate::only_debug! {
diff --git a/mingling_core/src/lib.rs b/mingling_core/src/lib.rs
index 9db0b03..c141a65 100644
--- a/mingling_core/src/lib.rs
+++ b/mingling_core/src/lib.rs
@@ -15,6 +15,7 @@ mod renderer;
mod tester;
+/// Provides a toolkit for `Mingling` testing capabilities.
pub mod test {
pub use crate::tester::*;
}
diff --git a/mingling_core/src/program/config.rs b/mingling_core/src/program/config.rs
index dcab526..ac541fd 100644
--- a/mingling_core/src/program/config.rs
+++ b/mingling_core/src/program/config.rs
@@ -46,14 +46,24 @@ pub struct ProgramUserContext {
#[cfg(feature = "general_renderer")]
#[derive(Debug, Clone, Default)]
+/// Settings for the general renderer output format.
+///
+/// Controls how structured data (e.g., JSON, YAML, TOML) is rendered to stdout.
pub enum GeneralRendererSetting {
+ /// Do not render structured output (use default formatting).
#[default]
Disable,
+ /// Render output as compact JSON.
Json,
+ /// Render output as pretty-printed JSON.
JsonPretty,
+ /// Render output as YAML.
Yaml,
+ /// Render output as TOML.
Toml,
+ /// Render output as RON.
Ron,
+ /// Render output as pretty-printed RON.
RonPretty,
}
diff --git a/mingling_core/src/program/string_vec.rs b/mingling_core/src/program/string_vec.rs
index 478ad74..fd0e2cb 100644
--- a/mingling_core/src/program/string_vec.rs
+++ b/mingling_core/src/program/string_vec.rs
@@ -1,4 +1,5 @@
#[derive(Debug, Clone)]
+#[doc(hidden)]
pub struct StringVec {
vec: Vec