Fix documentation in cardano-balance-tx. (#4234)

## Issue

ADP-3186

## Description

This PR fixes the documentation for selected functions in
`cardano-balance-tx`.

In particular, references to "the wallet" have been removed.

lib/balance-tx/lib/internal/Internal/Cardano/Write/Tx.hs

@@ -371,7 +371,9 @@ withConstraints era a = case era of
     RecentEraBabbage -> a
     RecentEraConway -> a
 
--- | Return a proof that the wallet can create txs in this era, or @Nothing@.
+-- | Returns a proof that the given era is a recent era.
+--
+-- Otherwise, returns @Nothing@.
 toRecentEra :: CardanoApi.CardanoEra era -> Maybe (RecentEra era)
 toRecentEra = \case
     CardanoApi.ConwayEra  -> Just RecentEraConway

lib/balance-tx/lib/internal/Internal/Cardano/Write/Tx/Balance.hs

@@ -1169,10 +1169,20 @@ selectAssets era (ProtocolParameters pp) utxoAssumptions outs redeemers
         extraBytes = 8
 
 data ChangeAddressGen s = ChangeAddressGen
-    { getChangeAddressGen :: s -> (Address, s)
+    {
+    -- | Generates a new change address.
+    --
+    genChangeAddress :: s -> (Address, s)
 
-    -- | Returns the longest address that the wallet can generate for a given
-    --   key.
+    -- | Returns a /dummy/ change address of the maximum possible length for
+    --   this generator.
+    --
+    -- Implementations must satisfy the following property:
+    --
+    -- @
+    -- ∀ s. length (fst (genChangeAddress s)) <=
+    --      length maxLengthChangeAddress
+    -- @
     --
     -- This is useful in situations where we want to compute some function of
     -- an output under construction (such as a minimum UTxO value), but don't
@@ -1186,9 +1196,7 @@ data ChangeAddressGen s = ChangeAddressGen
     , maxLengthChangeAddress :: Address
     }
 
--- | Augments the given outputs with new outputs. These new outputs correspond
--- to change outputs to which new addresses have been assigned. This updates
--- the wallet state as it needs to keep track of new pending change addresses.
+-- | Assigns addresses to the change outputs of the given selection.
 assignChangeAddresses
     :: ChangeAddressGen s
     -> SelectionOf W.TokenBundle

lib/wallet/test/unit/Internal/Cardano/Write/Tx/BalanceSpec.hs

@@ -596,7 +596,7 @@ spec_balanceTransaction = describe "balanceTransaction" $ do
         let expectedChange = fmap Convert.toWalletAddress <$>
                 flip evalState s0
                 $ replicateM nChange
-                $ state @Identity (getChangeAddressGen dummyChangeAddrGen)
+                $ state @Identity (genChangeAddress dummyChangeAddrGen)
 
         let address :: Babbage.BabbageTxOut StandardBabbage -> W.Address
             address (Babbage.BabbageTxOut addr _ _ _) = Convert.toWallet addr
@@ -2312,7 +2312,7 @@ costModelsForTesting = either (error . show) id $ do
 
 dummyChangeAddrGen :: ChangeAddressGen DummyChangeState
 dummyChangeAddrGen = ChangeAddressGen
-    { getChangeAddressGen = \(DummyChangeState i) ->
+    { genChangeAddress = \(DummyChangeState i) ->
         (addressAtIx $ toEnum i, DummyChangeState $ succ i)
     , maxLengthChangeAddress = addressAtIx minBound
     }