OPT: add SOAP fault notes 📝

kpn · Nov 27, 2023 · 52aee00 · 52aee00
1 parent 2e3ea7e
commit 52aee00
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 7 deletions.
diff --git a/combadge/support/soap/response.py b/combadge/support/soap/response.py
@@ -7,15 +7,20 @@
 
 class BaseSoapFault(ErrorResponse):
     """
-    SOAP Fault model.
+    [SOAP Fault][1] error response model.
 
-    Notes:
-        - This class matches the SOAP Fault specification.
-          For custom errors returned in a SOAP response body (such as `<error>` tag),
-          subclass the `ErrorResponse`.
+    [1]: https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383507
 
-    See Also:
-        - https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383507
+    Note: This class is intended for use with the SOAP Fault specification
+        For custom errors returned in a SOAP response body (such as `<error>` tag),
+        subclass the `ErrorResponse`.
+
+    Tip:
+        SOAP backends should **always** fall back to `BaseSoapFault` if the actual SOAP fault
+        does not match any of the protocol's return types.
+
+        For client developers, this means that it is a good idea to include `BaseSoapFault`
+        as the last possible `Union` variant to let users know that is should be handled.
     """
 
     code: str

diff --git a/docs/support/soap.md b/docs/support/soap.md
@@ -15,3 +15,10 @@ tags:
     options:
       heading_level: 3
       show_bases: true
+
+## Responses
+
+::: combadge.support.soap.response
+    options:
+      heading_level: 3
+      show_bases: true