Update haddock after new info from Micha.

bench/tx-generator/src/Cardano/Benchmarking/Script/Core.hs

@@ -298,6 +298,11 @@ evalGenerator generator txParams@TxGenTxParams{txParamFee = fee} era = do
           return $ Right tx
       return $ Streaming.effect (Streaming.yield <$> gen)
 
+    -- 'Split' combines regular payments and payments for change.
+    -- There are lists of payments buried in the 'PayWithChange'
+    -- type conditionally sent back by 'Utils.includeChange', to
+    -- then be used while partially applied as the @valueSplitter@
+    -- in 'sourceToStoreTransactionNew'.
     Split walletName payMode payModeChange coins -> do
       wallet <- getEnvWallets walletName
       (toUTxO, addressOut) <- interpretPayMode payMode
@@ -311,6 +316,11 @@ evalGenerator generator txParams@TxGenTxParams{txParamFee = fee} era = do
         sourceToStore = sourceToStoreTransactionNew txGenerator fundSource inToOut $ mangleWithChange toUTxOChange toUTxO
       return $ Streaming.effect (Streaming.yield <$> sourceToStore)
 
+    -- The 'SplitN' case's call chain is somewhat elaborate.
+    -- The division is done in 'Utils.inputsToOutputsWithFee' 
+    -- but things are threaded through
+    -- 'Cardano.Benchmarking.Wallet.mangle' and packed into
+    -- the transaction assembled by 'sourceToStoreTransactionNew'.
     SplitN walletName payMode count -> do
       wallet <- getEnvWallets walletName
       (toUTxO, addressOut) <- interpretPayMode payMode

bench/tx-generator/src/Cardano/Benchmarking/Script/Types.hs

@@ -135,11 +135,14 @@ data Generator where
   -- 'Cardano.TxGenerator.Genesis.genesisSecureInitialFundForKey'.
   -- This is where streams of transactions start.
   SecureGenesis :: !String -> !String -> !String -> Generator -- 0 to N
-  -- 'Split' is difficult to interpret as a particular kind of
-  -- transaction, but appears limited to 3 participants.
+  -- | 'Split' makes payments with change depending on the pay mode.
+  -- The splitting is from potentially sending the change to a
+  -- different place.
   Split :: !String -> !PayMode -> !PayMode -> [ Lovelace ] -> Generator
-  -- 'SplitN' seems to infinitely 'repeat' the operation but
-  -- it's less clear where the fee came from or other things.
+  -- | 'SplitN' divides the funds by N and divides them up into that
+  -- many transactions in a finite sequence. The handling starts from
+  -- a case in 'Cardano.Benchmarking.Script.Core.evalGenerator' and
+  -- has some complexity to it.
   SplitN :: !String -> !PayMode -> !Int -> Generator            -- 1 to N
   -- 'NtoM' seems like it should issue a single N-to-M transaction,
   -- but it's difficult to tell what it's doing.

bench/tx-generator/src/Cardano/Benchmarking/Wallet.hs

@@ -64,11 +64,25 @@ walletPreview ref munch = do
   fifo <- readMVar ref
   return $ maybe (toList fifo) snd (removeFunds munch fifo)
 
+-- | The second argument to 'mangleWithChange' is hidden in the
+-- 'CreateAndStoreList' type. When there is change to be made,
+-- it makes separate transactions to pay the change and sends
+-- them off to 'mangle' to get zips of applications.
 mangleWithChange :: Monad m => CreateAndStore m era -> CreateAndStore m era -> CreateAndStoreList m era PayWithChange
 mangleWithChange mkChange mkPayment outs = case outs of
   PayExact l -> mangle (repeat mkPayment) l
   PayWithChange change payments -> mangle (mkChange : repeat mkPayment) (change : payments)
 
+-- | The second argument to 'mangle' is hidden in the
+-- 'CreateAndStoreList' type. This is basically
+-- @second (\x -> (mapM_ ($ x)))
+-- . unzip
+-- $ zipWith3 (\x y z -> second ($ z) (x y))@
+-- but relatively obfuscated.
+-- This appears to mostly be list processing and function application.
+-- and gets used by 'Cardano.Bencharking.Script.Core.evalGenerator'
+-- to handle several of the cases of
+-- 'Cardano.Benchmarking.Script.Types.Generator'
 mangle :: Monad m => [ CreateAndStore m era ] -> CreateAndStoreList m era [ Lovelace ]
 mangle fkts values 
   = (outs, \txId -> mapM_ (\f -> f txId) fs)

bench/tx-generator/src/Cardano/TxGenerator/Utils.hs

@@ -39,6 +39,9 @@ inputsToOutputsWithFee fee count inputs = map (quantityToLovelace . Quantity) ou
     (out, rest) = divMod totalAvailable (fromIntegral count)
     outputs = (out + rest) : replicate (count-1) out
 
+-- | 'includeChange' gets use made of it as a value splitter in
+-- 'Cardano.TxGenerator.Tx.sourceToStoreTransactionNew' by
+-- 'Cardano.Benchmarking.Script.Core.evalGenerator'.
 includeChange :: Lovelace -> [Lovelace] -> [Lovelace] -> PayWithChange
 includeChange fee spend have = case compare changeValue 0 of
   GT -> PayWithChange changeValue spend