docs(comp): improve documentation for completion module

Add detailed doc comments, examples, and usage notes across
the completion module including ShellContext, Suggest, and
related traits.

1 files changed, 17 insertions, 1 deletions

diff --git a/mingling_core/src/comp/flags.rs b/mingling_core/src/comp/flags.rs
index 6285570..490c88b 100644
--- a/mingling_core/src/comp/flags.rs
+++ b/mingling_core/src/comp/flags.rs
@@ -1,10 +1,26 @@
-// Doc Not Optimize
 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.
+///
+/// # Behavior under `structural_renderer` feature
+///
+/// When the `structural_renderer` feature is enabled, this enum derives
+/// [`serde::Serialize`](https://docs.rs/serde/latest/serde/trait.Serialize.html).
+/// The serialization produces shell-specific string identifiers:
+///
+/// - `Bash` serializes to `"bash"`
+/// - `Zsh` serializes to `"zsh"`
+/// - `Fish` serializes to `"fish"`
+/// - `Powershell` serializes to `"powershell"`
+/// - `Other(name)` serializes to the inner string value
+///
+/// This allows the shell type to be transmitted as a plain string over
+/// serialization boundaries (e.g., JSON, YAML) when using structural
+/// rendering, while deserialization is handled by a separate process
+/// (such as the `From<String>` implementation).
 #[derive(Default, Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "structural_renderer", derive(serde::Serialize))]
 pub enum ShellFlag {