From 40cfa2a22391dfad6400373f57b7249d8d7e3dcc Mon Sep 17 00:00:00 2001
From: Jeremiah Russell <jerry@jrussell.ie>
Date: Fri, 17 Oct 2025 17:22:34 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(lib):=20add=20detailed=20do?=
 =?UTF-8?q?cumentation=20for=20library=20features?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- add gmail query syntax guide
- provide performance and limits information
- explain logging functionality
- describe security considerations
- include troubleshooting section
- add "see also" links
---
 docs/lib.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/docs/lib.md b/docs/lib.md
index 6519c4e..0c4f184 100644
--- a/docs/lib.md
+++ b/docs/lib.md
@@ -231,3 +231,105 @@ async fn main() -> cull_gmail::Result<()> {
 }
 ```
 
+## Gmail Query Syntax
+
+The library supports Gmail's search syntax for message queries:
+
+```rust path=null start=null
+// Date-based queries
+client.set_query("older_than:1y");           // Older than 1 year
+client.set_query("newer_than:30d");          // Newer than 30 days
+client.set_query("after:2023/1/1");          // After specific date
+
+// Label-based queries
+client.set_query("label:promotions");        // Has promotions label
+client.set_query("-label:important");        // Does NOT have important label
+
+// Content queries
+client.set_query("subject:newsletter");      // Subject contains "newsletter"
+client.set_query("from:noreply@example.com"); // From specific sender
+
+// Combined queries
+client.set_query("label:promotions older_than:6m -is:starred");
+```
+
+## Performance & Limits
+
+### Pagination
+
+- Default page size: 200 messages
+- Use `client.set_max_results(n)` to adjust
+- Use `client.get_messages(0)` to get all pages
+- Use `client.get_messages(n)` to limit to n pages
+
+### Rate Limits
+
+- The library uses the official `google-gmail1` crate
+- Built-in retry logic for transient errors
+- Respects Gmail API quotas and limits
+
+### Batch Operations
+
+- Batch delete/trash operations are more efficient than individual calls
+- Operations are atomic - either all succeed or all fail
+
+## Logging
+
+The library uses the `log` crate for logging:
+
+```rust path=null start=null
+use env_logger;
+
+// Initialize logging
+env_logger::init();
+
+# Set log level via environment variable
+# RUST_LOG=cull_gmail=debug cargo run
+```
+
+Log levels:
+- `error`: Critical errors
+- `warn`: Warnings (e.g., missing labels, dry-run mode)
+- `info`: General information (e.g., message subjects, action results)
+- `debug`: Detailed operation info
+- `trace`: Very detailed debugging info
+
+## Security Considerations
+
+### OAuth2 Token Storage
+- Tokens are stored in `~/.cull-gmail/gmail1` by default
+- Tokens are automatically refreshed when expired
+- Revoke access in [Google Account settings](https://myaccount.google.com/permissions)
+
+### Required Scopes
+The library requires the `https://mail.google.com/` scope for full Gmail access.
+
+### Credential File Security
+- Store credential files securely (not in version control)
+- Use restrictive file permissions (600)
+- Consider using environment variables in production
+
+## Troubleshooting
+
+### Authentication Issues
+1. Verify credential file path and format
+2. Check OAuth2 client is configured for "Desktop Application"
+3. Ensure redirect URI matches configuration
+4. Clear token cache: `rm -rf ~/.cull-gmail/gmail1`
+
+### No Messages Found
+1. Verify label names exist: `client.show_label()`
+2. Test query syntax in Gmail web interface
+3. Check for typos in label names or query strings
+
+### Rate Limiting
+1. Reduce page size: `client.set_max_results(100)`
+2. Add delays between operations
+3. Check [Gmail API quotas](https://developers.google.com/gmail/api/reference/quota)
+
+## See Also
+
+- [CLI Documentation](main.md) - Complete guide to the command-line interface
+- [Examples Directory](../examples/) - Additional code examples and sample configurations
+- [API Documentation](https://docs.rs/cull-gmail) - Generated API reference
+- [Repository](https://github.com/jerus-org/cull-gmail) - Source code and issue tracking