google styled doc

mail_intake/adapters/gmail.py

@@ -1,6 +1,10 @@
 """
 Gmail adapter implementation for Mail Intake.
 
+---
+
+## Summary
+
 This module provides a **Gmail-specific implementation** of the
 `MailIntakeAdapter` contract.
 
@@ -30,15 +34,18 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
     Gmail REST API. It translates the generic mail intake contract into
     Gmail-specific API calls.
 
-    This class is the ONLY place where:
-    - googleapiclient is imported
-    - Gmail REST semantics are known
-    - .execute() is called
+    Notes:
+        **Responsibilities:**
 
-    Design constraints:
-    - Must remain thin and imperative
-    - Must not perform parsing or interpretation
-    - Must not expose Gmail-specific types beyond this class
+            - This class is the ONLY place where googleapiclient is imported
+            - Gmail REST semantics are known
+            - .execute() is called
+
+        **Constraints:**
+        
+            - Must remain thin and imperative
+            - Must not perform parsing or interpretation
+            - Must not expose Gmail-specific types beyond this class
     """
 
     def __init__(
@@ -50,9 +57,11 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Initialize the Gmail adapter.
 
         Args:
-            auth_provider: Authentication provider capable of supplying
-                valid Gmail API credentials.
-            user_id: Gmail user identifier. Defaults to `"me"`.
+            auth_provider (MailIntakeAuthProvider):
+                Authentication provider capable of supplying valid Gmail API credentials.
+
+            user_id (str):
+                Gmail user identifier. Defaults to `"me"`.
         """
         self._auth_provider = auth_provider
         self._user_id = user_id
@@ -64,10 +73,12 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Lazily initialize and return the Gmail API service client.
 
         Returns:
-            Initialized Gmail API service instance.
+            Any:
+                Initialized Gmail API service instance.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail service cannot be initialized.
+            MailIntakeAdapterError:
+                If the Gmail service cannot be initialized.
         """
         if self._service is None:
             try:
@@ -84,15 +95,16 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Iterate over message references matching the query.
 
         Args:
-            query: Gmail search query string.
+            query (str):
+                Gmail search query string.
 
         Yields:
-            Dictionaries containing:
-            - ``message_id``: Gmail message ID
-            - ``thread_id``: Gmail thread ID
+            Dict[str, str]:
+                Dictionaries containing ``message_id`` and ``thread_id``.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail API returns an error.
+            MailIntakeAdapterError:
+                If the Gmail API returns an error.
         """
         try:
             request = (
@@ -126,13 +138,16 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Fetch a full Gmail message by message ID.
 
         Args:
-            message_id: Gmail message identifier.
+            message_id (str):
+                Gmail message identifier.
 
         Returns:
-            Provider-native Gmail message payload.
+            Dict[str, Any]:
+                Provider-native Gmail message payload.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail API returns an error.
+            MailIntakeAdapterError:
+                If the Gmail API returns an error.
         """
         try:
             return (
@@ -151,13 +166,16 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Fetch a full Gmail thread by thread ID.
 
         Args:
-            thread_id: Gmail thread identifier.
+            thread_id (str):
+                Gmail thread identifier.
 
         Returns:
-            Provider-native Gmail thread payload.
+            Dict[str, Any]:
+                Provider-native Gmail thread payload.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail API returns an error.
+            MailIntakeAdapterError:
+                If the Gmail API returns an error.
         """
         try:
             return (