From 501d8a58307ba6bb2553a35692baa4663d5d1428 Mon Sep 17 00:00:00 2001 From: Jeremiah Russell Date: Sun, 19 Oct 2025 22:33:19 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(message-list):=20document?= =?UTF-8?q?=20trait=20and=20public=20methods=20with=20examples=20and=20err?= =?UTF-8?q?or=20semantics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/message_list.rs | 277 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 264 insertions(+), 13 deletions(-) diff --git a/src/message_list.rs b/src/message_list.rs index 8f1fdf4..f847af5 100644 --- a/src/message_list.rs +++ b/src/message_list.rs @@ -60,34 +60,285 @@ use google_gmail1::{ hyper_util::client::legacy::connect::HttpConnector, }; -/// Methods to select lists of messages from the mailbox +/// A trait for interacting with Gmail message lists, providing methods for +/// retrieving, filtering, and managing collections of Gmail messages. +/// +/// This trait abstracts the core operations needed to work with Gmail message lists, +/// including pagination, filtering by labels and queries, and configuring result limits. +/// +/// # Examples +/// +/// ```rust,no_run +/// use cull_gmail::{MessageList, GmailClient, ClientConfig}; +/// +/// # async fn example() -> Result<(), Box> { +/// let config = ClientConfig::builder().build(); +/// let mut client = GmailClient::new_with_config(config).await?; +/// +/// // Set search parameters +/// client.set_query("is:unread"); +/// client.set_max_results(100); +/// +/// // Retrieve first page of messages +/// client.get_messages(1).await?; +/// # Ok(()) +/// # } +/// ``` pub trait MessageList { - /// Log the initial characters of the subjects of the message in the list + /// Fetches detailed metadata for stored messages and logs their subjects and dates. + /// + /// This method retrieves the subject line and date for each message currently + /// stored in the message list and outputs them to the log. + /// + /// # Returns + /// + /// Returns `Result<()>` on success, or an error if the Gmail API request fails. + /// + /// # Errors + /// + /// This method can fail if: + /// - The Gmail API is unreachable + /// - Authentication credentials are invalid or expired + /// - Network connectivity issues occur + /// - Individual message retrieval fails fn log_messages(&mut self) -> impl std::future::Future> + Send; - /// List of messages + + /// Retrieves a list of messages from Gmail based on current filter settings. + /// + /// This method calls the Gmail API to get a page of messages matching the + /// configured query and label filters. Retrieved message IDs are stored + /// internally for further operations. + /// + /// # Arguments + /// + /// * `next_page_token` - Optional token for pagination. Use `None` for the first page, + /// or the token from a previous response to get subsequent pages. + /// + /// # Returns + /// + /// Returns the raw `ListMessagesResponse` from the Gmail API, which contains + /// message metadata and pagination tokens. + /// + /// # Errors + /// + /// This method can fail if: + /// - The Gmail API request fails + /// - Authentication is invalid + /// - The query syntax is malformed + /// - Network issues prevent the API call + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::{MessageList, GmailClient, ClientConfig}; + /// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> { + /// // Get the first page of results + /// let response = client.list_messages(None).await?; + /// + /// // Get the next page if available + /// if let Some(token) = response.next_page_token { + /// let next_page = client.list_messages(Some(token)).await?; + /// } + /// # Ok(()) + /// # } + /// ``` fn list_messages( &mut self, next_page_token: Option, ) -> impl std::future::Future> + Send; - /// Run something + + /// Retrieves multiple pages of messages based on the specified page limit. + /// + /// This method handles pagination automatically, fetching the specified number + /// of pages or all available pages if `pages` is 0. + /// + /// # Arguments + /// + /// * `pages` - Number of pages to retrieve: + /// - `0`: Fetch all available pages + /// - `1`: Fetch only the first page + /// - `n > 1`: Fetch exactly `n` pages or until no more pages are available + /// + /// # Returns + /// + /// Returns `Result<()>` on success. All retrieved messages are stored internally + /// and can be accessed via `messages()`. + /// + /// # Errors + /// + /// This method can fail if any individual page request fails. See `list_messages` + /// for specific error conditions. + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::{MessageList, GmailClient, ClientConfig}; + /// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> { + /// // Get all available pages + /// client.get_messages(0).await?; + /// + /// // Get exactly 3 pages + /// client.get_messages(3).await?; + /// # Ok(()) + /// # } + /// ``` fn get_messages(&mut self, pages: u32) -> impl std::future::Future> + Send; - /// Return the gmail hub + + /// Returns a reference to the Gmail API hub for direct API access. + /// + /// This method provides access to the underlying Gmail API client for + /// advanced operations not covered by this trait. + /// + /// # Returns + /// + /// A cloned `Gmail` hub instance configured with the appropriate connectors. fn hub(&self) -> Gmail>; - /// Return the list of label_ids + + /// Returns the list of label IDs currently configured for message filtering. + /// + /// # Returns + /// + /// A vector of Gmail label ID strings. These IDs are used to filter + /// messages during API calls. + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::MessageList; + /// # fn example(client: impl MessageList) { + /// let labels = client.label_ids(); + /// println!("Filtering by {} labels", labels.len()); + /// # } + /// ``` fn label_ids(&self) -> Vec; - /// Return the list of message ids + + /// Returns a list of message IDs for all currently stored messages. + /// + /// # Returns + /// + /// A vector of Gmail message ID strings. These IDs can be used for + /// further Gmail API operations on specific messages. + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::MessageList; + /// # fn example(client: impl MessageList) { + /// let message_ids = client.message_ids(); + /// println!("Found {} messages", message_ids.len()); + /// # } + /// ``` fn message_ids(&self) -> Vec; - /// Return a summary of the messages (id and summary) + + /// Returns a reference to the collection of message summaries. + /// + /// This method provides access to all message summaries currently stored, + /// including any metadata that has been fetched. + /// + /// # Returns + /// + /// A reference to a vector of `MessageSummary` objects containing + /// message IDs and any retrieved metadata. fn messages(&self) -> &Vec; - /// Set the query for the message list + + /// Sets the search query string for filtering messages. + /// + /// This method configures the Gmail search query that will be used in + /// subsequent API calls. The query uses Gmail's search syntax. + /// + /// # Arguments + /// + /// * `query` - A Gmail search query string (e.g., "is:unread", "from:example@gmail.com") + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::MessageList; + /// # fn example(mut client: impl MessageList) { + /// client.set_query("is:unread older_than:30d"); + /// client.set_query("from:noreply@example.com"); + /// # } + /// ``` fn set_query(&mut self, query: &str); - /// Add label ids to the list of labels for the message list + + /// Adds Gmail label IDs to the current filter list. + /// + /// This method appends the provided label IDs to the existing list of + /// labels used for filtering messages. Messages must match ALL specified labels. + /// + /// # Arguments + /// + /// * `label_ids` - A slice of Gmail label ID strings to add to the filter + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::MessageList; + /// # fn example(mut client: impl MessageList) { + /// let label_ids = vec!["Label_1".to_string(), "Label_2".to_string()]; + /// client.add_labels_ids(&label_ids); + /// # } + /// ``` fn add_labels_ids(&mut self, label_ids: &[String]); - /// Add labels to the list of labels for the message list + + /// Adds Gmail labels by name to the current filter list. + /// + /// This method resolves label names to their corresponding IDs and adds them + /// to the filter list. This is more convenient than using `add_labels_ids` + /// when you know the label names but not their IDs. + /// + /// # Arguments + /// + /// * `labels` - A slice of Gmail label name strings (e.g., "INBOX", "SPAM") + /// + /// # Returns + /// + /// Returns `Result<()>` on success, or an error if label name resolution fails. + /// + /// # Errors + /// + /// This method can fail if label name to ID resolution is not available + /// or if the underlying label ID mapping is not accessible. + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::MessageList; + /// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> { + /// let labels = vec!["INBOX".to_string(), "IMPORTANT".to_string()]; + /// client.add_labels(&labels)?; + /// # Ok(()) + /// # } + /// ``` fn add_labels(&mut self, labels: &[String]) -> Result<()>; - /// Report the max results value set + + /// Returns the current maximum results limit per API request. + /// + /// # Returns + /// + /// The maximum number of messages to retrieve in a single API call. + /// Default is typically 200. fn max_results(&self) -> u32; - /// Set the max_results value + + /// Sets the maximum number of results to return per API request. + /// + /// This controls how many messages are retrieved in each page when calling + /// the Gmail API. Larger values reduce the number of API calls needed but + /// increase memory usage and response time. + /// + /// # Arguments + /// + /// * `value` - Maximum results per page (typically 1-500, Gmail API limits apply) + /// + /// # Examples + /// + /// ```rust,no_run + /// # use cull_gmail::MessageList; + /// # fn example(mut client: impl MessageList) { + /// client.set_max_results(100); // Retrieve 100 messages per page + /// client.set_max_results(500); // Retrieve 500 messages per page (maximum) + /// # } + /// ``` fn set_max_results(&mut self, value: u32); }