1 files changed, 71 insertions, 21 deletions

diff --git a/mingling_core/src/comp.rs b/mingling_core/src/comp.rs
index 30b165a..4315854 100644
--- a/mingling_core/src/comp.rs
+++ b/mingling_core/src/comp.rs
@@ -1,11 +1,21 @@
-// Doc Not Optimize
+use crate::{ProgramCollect, debug, metadata::Description, this, trace};
+
+use std::collections::BTreeSet;
+use std::fmt::Display;
+
 mod comp_ctx;
 mod flags;
 mod shell_ctx;
 mod suggest;
 
-use std::collections::BTreeSet;
-use std::fmt::Display;
+#[doc(hidden)]
+pub use flags::*;
+
+#[doc(hidden)]
+pub use shell_ctx::*;
+
+#[doc(hidden)]
+pub use suggest::*;
 
 /// Constant defining the name of the completion subcommand.
 ///
@@ -15,42 +25,81 @@ use std::fmt::Display;
 ///
 /// This value is used internally by the completion system to intercept the
 /// command-line input and redirect to the completion handler.
+///
+/// ```
+/// # #[cfg(feature = "comp")] {
+/// # use mingling_core::COMPLETION_SUBCOMMAND;
+/// assert_eq!("__comp", COMPLETION_SUBCOMMAND);
+/// # }
+/// ```
 pub const COMPLETION_SUBCOMMAND: &str = "__comp";
 
-#[doc(hidden)]
-pub use flags::*;
-#[doc(hidden)]
-pub use shell_ctx::*;
-#[doc(hidden)]
-pub use suggest::*;
-
-use crate::{ProgramCollect, debug, metadata::Description, this, trace};
-
 #[cfg(feature = "debug")]
 use crate::debug::init_env_logger;
 
 #[cfg(not(feature = "dispatch_tree"))]
 use crate::ChainProcess;
+
 #[cfg(not(feature = "dispatch_tree"))]
 use crate::exec::match_user_input;
 
-/// Trait for implementing completion logic.
+/// Mingling Completion Entry Point
+///
+/// Defines the custom completion logic entry point for the program's shell
+/// completion system.
+///
+/// When a specific command node is matched, the `comp` method is called to
+/// generate completion suggestions based on the current shell context. Types
+/// implementing this trait are usually automatically generated by the
+/// [`dispatcher!`](https://docs.rs/mingling/latest/mingling/macros/macro.dispatcher.html)
+/// macro; users typically do not need to implement this trait manually.
+///
+/// # Manual impl
 ///
-/// This trait defines the interface for generating command-line completions.
-/// Types implementing this trait can provide custom completion suggestions
-/// based on the current shell context.
+/// If you need to implement it manually, follow the example below:
+///
+/// ```
+/// # #[cfg(feature = "comp")] {
+/// # use mingling_core::{Completion, CompletionHelper, ShellContext, Suggest};
+/// struct GreetCompletion;
+/// struct EntryGreet;
+///
+/// impl Completion for GreetCompletion {
+///     type Previous = EntryGreet;
+///
+///     fn comp(ctx: &ShellContext) -> Suggest {
+///         // Generate completion suggestions based on the shell context
+/// # Suggest::FileCompletion
+///     }
+/// }
+/// # }
+/// ```
 pub trait Completion {
-    /// The entry point type that the completion functionality will act on.
+    /// The previous type bound to this entry in the completion chain.
     ///
-    /// It marks the **previous** type, which typically represents an `EntryXXX` type
-    /// (unless you have specific requirements).
+    /// It is usually the first type generated by
+    /// [`Dispatcher`](https://docs.rs/mingling/latest/mingling/trait.Dispatcher.html).
     type Previous;
 
     /// Generates completion suggestions based on the current shell context.
     ///
     /// This method is called when the completion system needs to provide
-    /// custom suggestions for the current command or argument. Implementations
-    /// should use the provided [`ShellContext`] to determine what to suggest.
+    /// custom suggestions for the current command or arguments. Implementors
+    /// should decide what to suggest based on the provided [`ShellContext`].
+    ///
+    /// # Parameters
+    ///
+    /// * `ctx` — The current shell context information, including the command
+    ///   line content, cursor position, current word, previous word, etc.,
+    ///   used to determine what should be completed.
+    ///
+    /// # Returns
+    ///
+    /// Returns a [`Suggest`] enum value, which can be:
+    /// - [`Suggest::Suggest`] carrying a set of candidate suggestion items
+    ///   (`BTreeSet<SuggestItem>`), where each item may include a description.
+    /// - [`Suggest::FileCompletion`] instructs the shell to fall back to
+    ///   filesystem completion.
     fn comp(ctx: &ShellContext) -> Suggest;
 }
 
@@ -81,6 +130,7 @@ pub trait CompletionEntry {
 /// the current shell context and rendering the resulting suggestions in a
 /// format appropriate for the target shell.
 pub struct CompletionHelper;
+
 impl CompletionHelper {
     /// Executes the completion logic for the given program type (`P`).
     ///