Clarify balancing overview explanation and simplify references

cardano-api/internal/Cardano/Api/Experimental/Tx.hs

@@ -49,14 +49,14 @@ module Cardano.Api.Experimental.Tx
 
     -- |
     -- If we have a UTxO with exactly 12 ADA, we could just construct the transaction like in the
-    -- previous section directly, and it would be a valid transaction.
+    -- previous section directly, and it would be a valid transaction, but:
     --
-    -- That is because the requirement is that the sum of inputs of the transactions is equal to
-    -- the sum of the outputs, and that the fees specified are enough, and 2 ADA is more than enough
-    -- for fees of such a simple transaction on mainnet at the time of writing. But still, even if we
-    -- have exactly 12 ADA, it is unlikely that the fees required are exactly 2 ADA, so we are likely
-    -- wasting ADA on fees. Also, we may not always want to send all the ADA in the UTxO. So that is
-    -- were transaction balancing comes in.
+    --   * We are likely wasting ADA
+    --   * We may not have exactly one UTxO of 12 ADA
+    --   * Our transaciton may not be this simple
+    --
+    -- For these reasons, it is recommended that we balance the transaction before proceeding with
+    -- signing and submitting.
     --
     -- You can see how to balance a transaction in the documentation of the "Cardano.Api.Fees" module.
 

cardano-api/internal/Cardano/Api/Fees.hs

@@ -14,17 +14,25 @@
 module Cardano.Api.Fees
   ( -- * Introduction
 
-  --
-
     -- |
     -- The documentation of the "Cardano.Api.Tx.Body" module shows how to create a 'TxBodyContent' for a
     -- transaction that takes 12 ADA and sends 10 ADA to an address, and spends 2 ADA on fees. If we have a
-    -- UTxO with exactly 12 ADA, this would be a valid transaction.
+    -- UTxO with exactly 12 ADA, this would be a valid transaction, because it is balanced, and it has
+    -- enough fees, since 2 ADA is more than enough for fees of such a simple transaction on mainnet
+    -- at the time of writing.
+    --
+    -- A transaction is considered balanced if the value consumed is equivalent to the value produced.
+    -- In the simplest terms, a transaction that simply spends lovelace needs to be concerned with the
+    -- total lovelace that exists at the inputs, the output(s) and the transaction fee.
+    --
+    -- In other words:
+    --
+    -- @
+    -- inputs = outputs + fee
+    -- @
     --
-    -- The requirement is that the sum of inputs of the transactions is equal to the sum of the outputs,
-    -- and that the fees specified are enough, and 2 ADA is more than enough for fees of such a simple
-    -- transaction on mainnet at the time of writing. But still, even if we have exactly 12 ADA, it is
-    -- unlikely that the fees required are exactly 2 ADA, so we are likely wasting ADA on fees.
+    -- In this equation, the inputs would include the minted tokens, and the outputs would include the
+    -- destroyed tokens.
     --
     -- On the other hand, we don't always want to spend all the ADA from a UTxO. Balancing a transaction allows
     -- us to send the amount we want to send, pay only the necessary fees (or little more), and it

cardano-api/internal/Cardano/Api/Tx/Body.hs

@@ -131,14 +131,14 @@ module Cardano.Api.Tx.Body
 
     -- |
     -- If we have a UTxO with exactly 12 ADA, we could just construct the transaction like in the
-    -- previous section directly, and it would be a valid transaction.
+    -- previous section directly, and it would be a valid transaction, but:
     --
-    -- That is because the requirement is that the sum of inputs of the transactions is equal to
-    -- the sum of the outputs, and that the fees specified are enough, and 2 ADA is more than enough
-    -- for fees of such a simple transaction on mainnet at the time of writing. But still, even if we
-    -- have exactly 12 ADA, it is unlikely that the fees required are exactly 2 ADA, so we are likely
-    -- wasting ADA on fees. Also, we may not always want to send all the ADA in the UTxO. So that is
-    -- were transaction balancing comes in.
+    --   * We are likely wasting ADA
+    --   * We may not have exactly one UTxO of 12 ADA
+    --   * Our transaciton may not be this simple
+    --
+    -- For these reasons, it is recommended that we balance the transaction before proceeding with
+    -- signing and submitting.
     --
     -- You can see how to balance a transaction in the documentation of the "Cardano.Api.Fees" module.