google styled doc

openapi_first/errors.py

@@ -1,33 +1,34 @@
 """
-openapi_first.errors
-============================
+Exceptions for OpenAPI-first FastAPI applications.
 
-Custom exceptions for OpenAPI-first FastAPI applications.
+---
+
+## Summary
 
 This module defines a small hierarchy of explicit, intention-revealing
 exceptions used to signal contract violations between an OpenAPI
 specification and its Python implementation.
 
-Design principles
------------------
-- Errors represent *programmer mistakes*, not runtime conditions.
-- All errors are raised during application startup.
-- Messages are actionable and suitable for CI/CD output.
-- Exceptions are explicit rather than reused from generic built-ins.
+Notes:
+    **Design Principles:**
 
-These errors should normally cause immediate application failure.
+        - Errors represent programmer mistakes, not runtime conditions
+        - All errors are raised during application startup
+        - Messages are actionable and suitable for CI/CD output
+        - Exceptions are explicit rather than reused from generic built-ins
+
+    These errors should normally cause immediate application failure.
 """
 
 class OpenAPIFirstError(Exception):
     """
     Base exception for all OpenAPI-first enforcement errors.
 
-    This exception exists to allow callers, test suites, and CI pipelines
-    to catch and distinguish OpenAPI contract violations from unrelated
-    runtime errors.
+    Notes:
+        **Responsibilities:**
 
-    All exceptions raised by the OpenAPI-first core should inherit from
-    this type.
+            - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors
+            - All exceptions raised by the OpenAPI-first core should inherit from this type
     """
     pass
 
@@ -36,27 +37,28 @@ class MissingOperationHandler(OpenAPIFirstError):
     """
     Raised when an OpenAPI operation cannot be resolved to a handler.
 
-    This error occurs when:
-    - An OpenAPI operation does not define an operationId, or
-    - An operationId is defined but no matching function exists in the
-      provided routes module.
+    Notes:
+        **Scenarios:**
 
-    This represents a violation of the OpenAPI-first contract and
-    indicates that the specification and implementation are out of sync.
+            - An OpenAPI operation does not define an operationId
+            - An operationId is defined but no matching function exists in the provided routes module
+
+        **Guarantees:**
+
+            - This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync
     """
 
     def __init__(self, *, path: str, method: str, operation_id: str | None = None):
         """
-        Parameters
-        ----------
-        path : str
-            The HTTP path declared in the OpenAPI specification.
+        Initialize the error.
 
-        method : str
-            The HTTP method (as declared in the OpenAPI spec).
-
-        operation_id : str, optional
-            The operationId declared in the OpenAPI spec, if present.
+        Args:
+            path (str):
+                The HTTP path declared in the OpenAPI specification.
+            method (str):
+                The HTTP method (as declared in the OpenAPI spec).
+            operation_id (str, optional):
+                The operationId declared in the OpenAPI spec, if present.
         """
         if operation_id:
             message = (