From 257caf55ab6fc5890f13fd67b5dfab621dd1136e Mon Sep 17 00:00:00 2001
From: Jeremiah Russell <jerry@jrussell.ie>
Date: Sun, 19 Oct 2025 10:33:16 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(message-list):=20add=20modu?=
 =?UTF-8?q?le-level=20rustdoc=20with=20overview=20and=20usage=20example?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/message_list.rs | 55 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/src/message_list.rs b/src/message_list.rs
index 1fcb02f..8f1fdf4 100644
--- a/src/message_list.rs
+++ b/src/message_list.rs
@@ -1,3 +1,58 @@
+//! # Message List Module
+//!
+//! This module provides the `MessageList` trait for interacting with Gmail message lists.
+//! The trait defines methods for retrieving, filtering, and managing collections of Gmail messages.
+//!
+//! ## Overview
+//!
+//! The `MessageList` trait provides:
+//!
+//! - Message list retrieval with pagination support
+//! - Label and query-based filtering
+//! - Message metadata fetching and logging
+//! - Configuration of result limits and query parameters
+//!
+//! ## Error Handling
+//!
+//! All asynchronous methods return `Result<T>` where errors may include:
+//! - Gmail API communication errors
+//! - Authentication failures
+//! - Network connectivity issues
+//! - Invalid query parameters
+//!
+//! ## Threading
+//!
+//! All async methods in this trait are `Send` compatible, allowing them to be used
+//! across thread boundaries in concurrent contexts.
+//!
+//! ## Example
+//!
+//! ```rust,no_run
+//! use cull_gmail::{GmailClient, MessageList, ClientConfig};
+//!
+//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
+//!     // Create a client with proper configuration (credentials required)
+//!     let config = ClientConfig::builder()
+//!         .with_client_id("your-client-id")
+//!         .with_client_secret("your-client-secret")
+//!         .build();
+//!     let mut client = GmailClient::new_with_config(config).await?;
+//!     
+//!     // Configure search parameters
+//!     client.set_query("is:unread");
+//!     client.set_max_results(50);
+//!     
+//!     // Retrieve messages from Gmail
+//!     client.get_messages(1).await?;
+//!     
+//!     // Access retrieved message summaries
+//!     let messages = client.messages();
+//!     println!("Found {} messages", messages.len());
+//!     
+//!     Ok(())
+//! }
+//! ```
+
 use crate::{GmailClient, MessageSummary, Result};
 
 use google_gmail1::{