google styled doc

mail_intake/parsers/headers.py

@@ -1,6 +1,10 @@
 """
 Message header parsing utilities for Mail Intake.
 
+---
+
+## Summary
+
 This module provides helper functions for normalizing and extracting
 useful information from provider-native message headers.
 
@@ -15,29 +19,34 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]:
     """
     Convert a list of Gmail-style headers into a normalized dict.
 
-    Provider payloads (such as Gmail) typically represent headers as a list
-    of name/value mappings. This function normalizes them into a
-    case-insensitive dictionary keyed by lowercase header names.
-
     Args:
-        raw_headers: List of header dictionaries, each containing
-            ``name`` and ``value`` keys.
+        raw_headers (List[Dict[str, str]]):
+            List of header dictionaries, each containing ``name`` and ``value`` keys.
 
     Returns:
-        Dictionary mapping lowercase header names to stripped values.
+        Dict[str, str]:
+            Dictionary mapping lowercase header names to stripped values.
+
+    Notes:
+        **Guarantees:**
+
+            - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings
+            - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names
 
     Example:
-        Input:
-            [
-                {"name": "From", "value": "John Doe <john@example.com>"},
-                {"name": "Subject", "value": "Re: Interview Update"},
-            ]
-
-        Output:
-            {
-                "from": "John Doe <john@example.com>",
-                "subject": "Re: Interview Update",
-            }
+        Typical usage:
+        
+            Input:
+                [
+                    {"name": "From", "value": "John Doe <john@example.com>"},
+                    {"name": "Subject", "value": "Re: Interview Update"},
+                ]
+    
+            Output:
+                {
+                    "from": "John Doe <john@example.com>",
+                    "subject": "Re: Interview Update",
+                }
     """
     headers: Dict[str, str] = {}
 
@@ -57,22 +66,24 @@ def extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]:
     """
     Extract sender email and optional display name from headers.
 
-    This function parses the ``From`` header and attempts to extract:
-    - Sender email address
-    - Optional human-readable display name
-
     Args:
-        headers: Normalized header dictionary as returned by
-            :func:`parse_headers`.
+        headers (Dict[str, str]):
+            Normalized header dictionary as returned by :func:`parse_headers`.
 
     Returns:
-        A tuple ``(email, name)`` where:
-        - ``email`` is the sender email address
-        - ``name`` is the display name, or ``None`` if unavailable
+        Tuple[str, Optional[str]]:
+            A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.
 
-    Examples:
-        ``"John Doe <john@example.com>"`` → ``("john@example.com", "John Doe")``
-        ``"john@example.com"`` → ``("john@example.com", None)``
+    Notes:
+        **Responsibilities:**
+
+            - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name
+
+    Example:
+        Typical values:
+
+            ``"John Doe <john@example.com>"`` -> ``("john@example.com", "John Doe")``
+            ``"john@example.com"`` -> ``("john@example.com", None)``
     """
     from_header = headers.get("from")
     if not from_header: