📝 Add docstrings to codex/fix-cache-key-comparison-logic (#292)

Docstrings generation was requested by @shayancoin.

* #150 (comment)

The following files were modified:

* `backend/api/config.py`
* `backend/api/instrumentation_boot.py`
* `backend/api/main.py`
* `backend/api/metrics.py`

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Shayan <shayan@coin.link>

Author: coderabbitai[bot]

backend/api/config.py

@@ -76,7 +76,18 @@ class Settings(BaseSettings):
     @field_validator("hygraph_webhook_secret")
     @classmethod
     def _validate_hygraph_webhook_secret(cls, value: str) -> str:
-        """Ensure the Hygraph webhook secret is populated and trimmed."""
+        """
+        Validate and return a trimmed Hygraph webhook secret.
+        
+        Parameters:
+            value (str): The raw webhook secret from environment or configuration.
+        
+        Returns:
+            str: The webhook secret with surrounding whitespace removed.
+        
+        Raises:
+            ValueError: If `value` is empty or contains only whitespace.
+        """
 
         if not value or not value.strip():
             raise ValueError(
@@ -113,12 +124,22 @@ def get_settings() -> Settings:
 
 
 def get_fastapi_settings() -> Dict[str, Any]:
-    """Get FastAPI application metadata for documentation UIs."""
+    """
+    Provide FastAPI application metadata used by documentation UIs.
+    
+    Returns:
+        dict: Mapping with the FastAPI documentation settings:
+            - "title": API title.
+            - "description": Short API description.
+            - "version": API version string.
+            - "docs_url": URL path for the Swagger UI.
+            - "redoc_url": URL path for the ReDoc UI.
+    """
 
     return {
         "title": "MVP API",
         "description": "API for MVP application",
         "version": "0.1.0",
         "docs_url": "/docs",
         "redoc_url": "/redoc",
-    }
+    }

backend/api/metrics.py

@@ -119,7 +119,23 @@ def observe_http_request(
     status_code: int | str,
     duration_seconds: float,
 ) -> None:
-    """Record a single HTTP request observation."""
+    """
+    Record metrics for a single HTTP request.
+    
+    Parameters:
+        service (str): Logical service name to label the metric (written to `service` / `service.name`).
+        route (str): Request route to label the metric (written to `route` / `http.route`).
+        method (str): HTTP method to label the metric (written to `method` / `http.method`).
+        status_code (int | str): HTTP status code used as the `status` label; if an integer can be derived,
+            it is also recorded as the `http.status_code` attribute for OpenTelemetry metrics.
+        duration_seconds (float): Request duration in seconds to record in latency histograms.
+    
+    Description:
+        Increments the Prometheus request counter and records the request duration histogram using the
+        provided labels. If OpenTelemetry metrics are initialized, records equivalent OTEL counter and
+        histogram measurements with attributes `service.name`, `http.route`, `http.method`, and
+        `http.status_code` (when `status_code` can be coerced to an integer).
+    """
 
     status_label = str(status_code)
     http_requests_total.labels(
@@ -148,9 +164,15 @@ def observe_http_request(
 
 
 def observe_lcp(*, app: str, seconds: float) -> None:
-    """Record a Largest Contentful Paint measurement in seconds."""
+    """Record a Largest Contentful Paint (LCP) measurement for an application.
+    
+    Records the value to the module's LCP histogram and, when OpenTelemetry is initialized, to the OTEL LCP histogram with the `app` attribute.
+    
+    Parameters:
+        app (str): Application identifier used as the metric label.
+        seconds (float): LCP value in seconds.
+    """
 
     web_vitals_lcp.labels(app=app).observe(seconds)
     if _web_vitals_lcp_histogram is not None:
         _web_vitals_lcp_histogram.record(seconds, {"app": app})
-