Add missing articles and improve documentation

8 files changed, 55 insertions, 0 deletions

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<String>;
 }
 
+/// A helper struct for handling command-line completion logic.
+///
+/// This struct provides static methods for executing completions based on
+/// the current shell context and rendering the resulting suggestions in a
+/// format appropriate for the target shell.
 pub struct CompletionHelper;
 impl CompletionHelper {
     pub fn exec_completion<P>(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<String>,
 }
diff --git a/mingling_core/src/renderer/general.rs b/mingling_core/src/renderer/general.rs
index 4ca2683..3808e5a 100644
--- a/mingling_core/src/renderer/general.rs
+++ b/mingling_core/src/renderer/general.rs
@@ -4,6 +4,13 @@ use crate::{
 use serde::Serialize;
 
 pub mod error;
+
+/// A general renderer that supports multiple serialization formats.
+///
+/// The `GeneralRenderer` provides methods to serialize data into various formats
+/// including JSON, YAML, TOML, and RON, with support for both regular and
+/// pretty-printed variants. It is designed to work with types that implement
+/// the `Serialize` trait.
 pub struct GeneralRenderer;
 
 impl GeneralRenderer {