📝 docs(cli): add comprehensive documentation for labels and messages modules

- Add extensive module-level documentation for labels_cli with usage examples
- Document complete messages_cli module with Gmail query syntax guide
- Add comprehensive struct and method documentation with safety considerations
- Include detailed parameter explanations and error handling guidance
- Document action types with safety levels and reversibility information
- Add practical usage patterns and safety recommendations
- Include extensive examples of Gmail query syntax and filtering options

src/cli/labels_cli.rs

@@ -1,10 +1,123 @@
+//! # Gmail Labels CLI Module
+//!
+//! This module provides command-line interface functionality for inspecting and displaying
+//! Gmail labels. It enables users to list all available labels in their Gmail account
+//! along with their internal Gmail IDs and display names.
+//!
+//! ## Purpose
+//!
+//! The labels command is essential for:
+//! - Understanding the structure of Gmail labels in an account
+//! - Finding correct label names for use in message queries
+//! - Inspecting label IDs for advanced Gmail API usage
+//! - Verifying label availability before creating rules
+//!
+//! ## Usage
+//!
+//! ```bash
+//! cull-gmail labels
+//! ```
+//!
+//! ## Output Format
+//!
+//! The command displays labels in a human-readable format showing:
+//! - **Label Name**: User-visible label name
+//! - **Label ID**: Internal Gmail identifier
+//!
+//! Example output:
+//! ```text
+//! INBOX: INBOX
+//! IMPORTANT: IMPORTANT  
+//! promotions: Label_1234567890
+//! newsletters: Label_0987654321
+//! ```
+//!
+//! ## Integration
+//!
+//! This module integrates with:
+//! - **GmailClient**: For Gmail API communication and authentication
+//! - **Main CLI**: As a subcommand in the primary CLI application
+//! - **Error handling**: Using the unified crate error types
+
 use clap::Parser;
 use cull_gmail::{Error, GmailClient};
 
+/// Command-line interface for Gmail label inspection and display.
+/// 
+/// This structure represents the `labels` subcommand, which provides functionality
+/// to list and inspect all Gmail labels available in the user's account. The command
+/// requires no additional arguments and displays comprehensive label information.
+/// 
+/// # Features
+/// 
+/// - **Complete label listing**: Shows all labels including system and user-created labels
+/// - **ID mapping**: Displays both human-readable names and internal Gmail IDs
+/// - **Simple usage**: No configuration or arguments required
+/// - **Authentication handling**: Automatic OAuth2 authentication through GmailClient
+/// 
+/// # Usage Context
+/// 
+/// This command is typically used:
+/// 1. **Before creating queries**: To understand available labels for message filtering
+/// 2. **Before configuring rules**: To verify target labels exist
+/// 3. **For debugging**: To inspect label structure and IDs
+/// 4. **For exploration**: To understand Gmail organization structure
+/// 
+/// # Examples
+/// 
+/// ```rust,no_run
+/// use cull_gmail::cli::labels_cli::LabelsCli;
+/// use cull_gmail::GmailClient;
+/// 
+/// # async fn example(client: GmailClient) -> Result<(), cull_gmail::Error> {
+/// let labels_cli = LabelsCli {};
+/// labels_cli.run(client).await?;
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug, Parser)]
 pub struct LabelsCli {}
 
 impl LabelsCli {
+    /// Executes the labels command to display Gmail label information.
+    /// 
+    /// This method coordinates the label inspection workflow by utilizing the
+    /// Gmail client to retrieve and display all available labels in the user's account.
+    /// The output includes both system labels (like INBOX, SENT) and user-created labels.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `client` - Authenticated Gmail client for API communication
+    /// 
+    /// # Returns
+    /// 
+    /// Returns `Result<(), Error>` indicating success or failure of the operation.
+    /// 
+    /// # Operation Details
+    /// 
+    /// The function performs the following steps:
+    /// 1. **Label Retrieval**: Fetches all labels from the Gmail API
+    /// 2. **Format Processing**: Organizes labels for display
+    /// 3. **Display Output**: Shows labels with names and IDs
+    /// 
+    /// # Output Format
+    /// 
+    /// Labels are displayed in the format:
+    /// ```text
+    /// <Label Name>: <Label ID>
+    /// ```
+    /// 
+    /// # Error Handling
+    /// 
+    /// Possible errors include:
+    /// - **Authentication failures**: OAuth2 token issues or expired credentials
+    /// - **API communication errors**: Network issues or Gmail API unavailability
+    /// - **Permission errors**: Insufficient OAuth2 scopes for label access
+    /// 
+    /// # Side Effects
+    /// 
+    /// This function produces output to stdout showing the label information.
+    /// No Gmail account modifications are performed.
     pub async fn run(&self, client: GmailClient) -> Result<(), Error> {
         client.show_label();
         Ok(())