docs: add comprehensive inline documentation for TxOut JSON parsing refactoring

This commit adds detailed inline documentation to explain the design decisions,
assumptions, and potential issues in the refactored TxOut JSON parsing code.

Key documentation areas:

1. parseBabbageOnwardsTxOut:
   - MOTIVATION: Explains this eliminates ~100 lines of duplication
   - DESIGN: Documents the two-phase parsing strategy (Alonzo + Babbage reconciliation)
   - ASSUMPTION: Notes BabbageEraOnwards covers exactly three eras

2. parseInlineDatum:
   - CRITICAL DISTINCTION: Explains why Babbage uses scriptDataJsonToHashable
     vs Conway+ using scriptDataFromJson (CBOR encoding preservation requirement)
   - VALIDATION: Documents hash verification logic
   - POTENTIAL ISSUE: Warns about wildcard pattern assumption

3. reconcileDatums:
   - BACKWARDS COMPATIBILITY: Lists the three valid JSON formats accepted
   - ERROR HANDLING: Explains conflicting datum detection and error messages
   - EXHAUSTIVENESS: Documents how direct GADT matching enables compiler verification
     when new eras are added to BabbageEraOnwards

4. eraName helper:
   - Documents switch from ShelleyBasedEra to direct BabbageEraOnwards matching
   - Explains benefit: compiler enforces exhaustiveness, preventing incomplete updates

Author: newhoggy

cardano-api/src/Cardano/Api/Tx/Internal/Output.hs

@@ -459,8 +459,21 @@ instance IsShelleyBasedEra era => FromJSON (TxOut CtxTx era) where
       ShelleyBasedEraConway -> parseBabbageOnwardsTxOut BabbageEraOnwardsConway o
       ShelleyBasedEraDijkstra -> parseBabbageOnwardsTxOut BabbageEraOnwardsDijkstra o
    where
-    -- Parse TxOut for Babbage+ eras
-    -- Handles both Alonzo-style (datumhash/datum) and Babbage-style (inlineDatumhash/inlineDatum) fields
+    -- Parse TxOut for Babbage+ eras (Babbage, Conway, Dijkstra)
+    --
+    -- MOTIVATION: This unified helper eliminates ~100 lines of duplication that previously
+    -- existed across the three Babbage+ era cases.
+    --
+    -- DESIGN: Uses a two-phase parsing strategy:
+    -- 1. Parse Alonzo-style fields (datumhash/datum) via alonzoTxOutParser
+    -- 2. Parse Babbage-style fields (inlineDatumhash/inlineDatum) via parseInlineDatum
+    -- 3. Reconcile both via reconcileDatums, which validates no conflicting datums exist
+    --
+    -- This approach maintains backwards compatibility - old JSON with only Alonzo fields
+    -- still parses correctly, while new JSON can use inline datums.
+    --
+    -- ASSUMPTION: BabbageEraOnwards will always cover exactly these three eras. If a new
+    -- era is added, this code must be updated.
     parseBabbageOnwardsTxOut
       :: BabbageEraOnwards era
       -> Aeson.Object
@@ -472,7 +485,20 @@ instance IsShelleyBasedEra era => FromJSON (TxOut CtxTx era) where
       reconcileDatums w alonzoTxOut inlineDatum mReferenceScript
 
     -- Parse inline datum fields from JSON object
-    -- Handles both inlineDatumhash and inlineDatum fields, validating they match
+    --
+    -- Handles both inlineDatumhash and inlineDatum fields, validating they match.
+    --
+    -- CRITICAL DISTINCTION: Babbage era uses scriptDataJsonToHashable (returns HashableScriptData)
+    -- while Conway+ uses scriptDataFromJson (returns ScriptData). This difference exists because
+    -- Babbage required preserving the original CBOR encoding for hash validation, while Conway+
+    -- can reconstruct it.
+    --
+    -- VALIDATION: When both hash and datum are present, we verify the datum hashes to the
+    -- provided hash. This catches malformed JSON where they don't match.
+    --
+    -- POTENTIAL ISSUE: The wildcard pattern (_ -> scriptDataFromJson) assumes all non-Babbage
+    -- eras in BabbageEraOnwards use scriptDataFromJson. If a future era needs different handling,
+    -- this must be updated to explicitly match all constructors.
     parseInlineDatum
       :: BabbageEraOnwards era
       -> Aeson.Object
@@ -500,7 +526,22 @@ instance IsShelleyBasedEra era => FromJSON (TxOut CtxTx era) where
             "Should not be possible to create a tx output with either an inline datum hash or an inline datum"
 
     -- Reconcile Alonzo-style and Babbage-style datums and reference scripts
-    -- This handles the two-phase parsing where both old and new style fields may be present
+    --
+    -- This handles the two-phase parsing where both old and new style fields may be present.
+    --
+    -- BACKWARDS COMPATIBILITY: Accepts JSON with either:
+    -- - Only Alonzo fields (datumhash/datum) - common in older transactions
+    -- - Only Babbage fields (inlineDatumhash/inlineDatum) - modern format
+    -- - Neither (TxOutDatumNone) - simple payment outputs
+    --
+    -- ERROR HANDLING: If *both* Alonzo and Babbage style datums are present, this is a
+    -- malformed JSON and we fail with a detailed error message showing both datums.
+    -- This should never happen in correctly formed JSON but protects against corruption.
+    --
+    -- EXHAUSTIVENESS: The eraName helper now matches directly on BabbageEraOnwards GADT
+    -- constructors instead of converting to ShelleyBasedEra. This allows the compiler to
+    -- verify exhaustiveness - if a new era is added to BabbageEraOnwards, this will fail
+    -- to compile, forcing developers to update the code.
     reconcileDatums
       :: BabbageEraOnwards era
       -> TxOut CtxTx era
@@ -533,6 +574,9 @@ instance IsShelleyBasedEra era => FromJSON (TxOut CtxTx era) where
         Just anyScript -> return $ ReferenceScript w anyScript
       return $ TxOut addr v finalDat finalRefScript
      where
+      -- Pattern match directly on GADT instead of converting to ShelleyBasedEra.
+      -- This enables exhaustiveness checking - adding a new era to BabbageEraOnwards
+      -- will cause a compile error here, preventing bugs from incomplete updates.
       eraName = case w of
         BabbageEraOnwardsBabbage -> "Babbage"
         BabbageEraOnwardsConway -> "Conway"