Fix links and address reviews

IntersectMBO · Feb 13, 2025 · a083ac2 · a083ac2
1 parent cec9101
commit a083ac2
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 34 deletions.
diff --git a/cardano-api/cardano-api.cabal b/cardano-api/cardano-api.cabal
@@ -74,6 +74,7 @@ library
     Cardano.Api.Internal.Eon.ShelleyBasedEra
     Cardano.Api.Internal.Eras
     Cardano.Api.Internal.Error
+    Cardano.Api.Internal.Experimental.Tx
     Cardano.Api.Internal.Fees
     Cardano.Api.Internal.Genesis
     Cardano.Api.Internal.GenesisParameters
@@ -89,6 +90,7 @@ library
     Cardano.Api.Internal.Script
     Cardano.Api.Internal.SerialiseLedgerCddl
     Cardano.Api.Internal.SerialiseTextEnvelope
+    Cardano.Api.Internal.Tx.Body
     Cardano.Api.Internal.Tx.Sign
     Cardano.Api.Ledger
     Cardano.Api.Ledger.Lens
@@ -193,7 +195,6 @@ library
     Cardano.Api.Internal.Eras.Case
     Cardano.Api.Internal.Eras.Core
     Cardano.Api.Internal.Experimental.Eras
-    Cardano.Api.Internal.Experimental.Tx
     Cardano.Api.Internal.Feature
     Cardano.Api.Internal.Governance.Actions.ProposalProcedure
     Cardano.Api.Internal.Governance.Actions.VotingProcedure
@@ -242,7 +243,6 @@ library
     Cardano.Api.Internal.SerialiseUsing
     Cardano.Api.Internal.SpecialByron
     Cardano.Api.Internal.StakePoolMetadata
-    Cardano.Api.Internal.Tx.Body
     Cardano.Api.Internal.Tx.Compatible
     Cardano.Api.Internal.TxIn
     Cardano.Api.Internal.TxMetadata

diff --git a/cardano-api/src/Cardano/Api/Experimental.hs b/cardano-api/src/Cardano/Api/Experimental.hs
@@ -6,7 +6,7 @@ module Cardano.Api.Experimental
 
     -- |
     -- For information and an example on how to create a transaction using the new experimental API,
-    -- check the documentation of the module "Cardano.Api.Experimental.Tx".
+    -- check the documentation of the module "Cardano.Api.Internal.Experimental.Tx".
 
     -- * Contents
 

diff --git a/cardano-api/src/Cardano/Api/Internal/Experimental/Tx.hs b/cardano-api/src/Cardano/Api/Internal/Experimental/Tx.hs
@@ -25,7 +25,7 @@ module Cardano.Api.Internal.Experimental.Tx
     -- This hasn't changed.
     --
     -- To see how to create a transaction using the old API, see the documentation
-    -- of the "Cardano.Api.Tx.Body" module.
+    -- of the "Cardano.Api.Internal.Tx.Body" module.
     --
     -- In the following examples, we are using the following qualified modules:
     --
@@ -36,20 +36,20 @@ module Cardano.Api.Internal.Experimental.Tx
     -- import qualified Cardano.Api.Experimental as Exp   -- the experimental API
     -- @
     --
-    -- You can find a compilable version of these examples in "Test.Cardano.Api.Experimental".
+    -- You can find a compilable version of these examples in @Test.Cardano.Api.Experimental@.
 
     -- ** Creating a 'TxBodyContent'
 
     -- |
     -- Independently of whether we use the Experimental or the traditoinal API, we need to create a 'TxBodyContent'.
     --
-    -- You can see how to do this in the documentation of the "Cardano.Api.Tx.Body" module.
+    -- You can see how to do this in the documentation of the "Cardano.Api.Internal.Tx.Body" module.
 
     -- ** Balancing a transaction
 
     -- |
-    -- 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, but:
+    -- If we have a UTxO with exactly 12 ADA, we could just construct the transaction as described in
+    -- "Cardano.Api.Internal.Tx.Body", and it would be a valid transaction, but:
     --
     --   * We are likely wasting ADA
     --   * We may not have exactly one UTxO of 12 ADA
@@ -58,14 +58,14 @@ module Cardano.Api.Internal.Experimental.Tx
     -- 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.
+    -- You can see how to balance a transaction in the documentation of the "Cardano.Api.Internal.Fees" module.
 
     -- ** Creating a 'ShelleyWitnessSigningKey'
 
     -- |
     -- To sign the transaction, we need a witness. For example, a 'ShelleyWitnessSigningKey'.
     --
-    -- You can see how to create a 'ShelleyWitnessSigningKey' in the documentation of the "Cardano.Api.Tx.Sign" module.
+    -- You can see how to create a 'ShelleyWitnessSigningKey' in the documentation of the "Cardano.Api.Internal.Tx.Sign" module.
 
     -- ** Creating a transaction using the new API
 

diff --git a/cardano-api/src/Cardano/Api/Internal/Fees.hs b/cardano-api/src/Cardano/Api/Internal/Fees.hs
@@ -15,15 +15,15 @@ module Cardano.Api.Internal.Fees
   ( -- * Introduction
 
     -- |
-    -- The documentation of the "Cardano.Api.Tx.Body" module shows how to create a 'TxBodyContent' for a
+    -- The documentation of the "Cardano.Api.Internal.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, 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.
+    -- A simple transaction that just spends UTxOs 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:
     --
@@ -35,7 +35,7 @@ module Cardano.Api.Internal.Fees
     -- 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
+    -- us to send the amount we want to send, pay only the necessary fees, and it
     -- allows us to calculate the amount of extra currency that we can send back to a change address.
     --
     -- Because changes to the transaction body will potentially change the amount of fees needed by a transaction,
@@ -72,9 +72,9 @@ module Cardano.Api.Internal.Fees
     -- @
     --
     -- 2. The protocol parameters for the current era. We can get them by using the 'QueryProtocolParameters'
-    -- query defined in "Cardano.Api.Query". Let's assume we have them in the @exampleProtocolParams@ variable.
+    -- query defined in "Cardano.Api.Internal.Query". Let's assume we have them in the @exampleProtocolParams@ variable.
     --
-    -- 3. The draft transaction body. We can get it by using 'createTransactionBody' defined in "Cardano.Api.Tx.Body":
+    -- 3. The draft transaction body. We can get it by using 'createTransactionBody' defined in "Cardano.Api.Internal.Tx.Body":
     --
     -- @
     -- let (Right txBody) = Api.createTransactionBody sbe txBodyContent
@@ -104,10 +104,10 @@ module Cardano.Api.Internal.Fees
     -- * 1 input of 12 ADA (from the UTxO)
     -- * 1 output of 10 ADA (to the address we want to pay)
     -- * 1 output of 1.8 ADA (to the change address)
-    -- * 0.2 ADA in fees
+    -- * 0.2 ADA in fees (the amount of fees calculated, in this case an overestimation)
     --
     -- So, we would have to update our 'TxBodyContent' accordingly, and continue with the
-    -- transaction building as we demonstrate in the 'Cardano.Api.Experimental.Tx' module
+    -- transaction building as we demonstrate in the "Cardano.Api.Internal.Experimental.Tx" module
 
     -- ** Example 2: Automated balancing without chain info (no UTxO, no ledger state)
 
@@ -125,11 +125,11 @@ module Cardano.Api.Internal.Fees
     -- let meo = Api.MaryEraOnwardsConway
     -- @
     --
-    -- 2. The draft 'TxBodyContent' for the transaction we want to balance. In "Cardano.Api.Tx.Body" we show
+    -- 2. The draft 'TxBodyContent' for the transaction we want to balance. In "Cardano.Api.Internal.Tx.Body" we show
     -- how to create one. We assume we have it in the @txBodyContent@ variable.
     --
     -- 3. The protocol parameters for the current era. We can get them by using the 'QueryProtocolParameters'
-    -- query defined in "Cardano.Api.Query". Let's assume we have them in the @exampleProtocolParams@ variable.
+    -- query defined in "Cardano.Api.Internal.Query". Let's assume we have them in the @exampleProtocolParams@ variable.
     --
     -- 4. For stake pool and gov actions, we will also need:
     --
@@ -154,7 +154,7 @@ module Cardano.Api.Internal.Fees
     --       this would be @0@.
     --
     -- 6. The address where we want to send the change. We can deserialise it from its bech32 representation
-    -- by using the 'deserialiseAddress' function defined in "Cardano.Api.Address":
+    -- by using the 'deserialiseAddress' function defined in "Cardano.Api.Internal.Address":
     --
     -- @
     -- let Just exampleChangeAddress =
@@ -229,14 +229,14 @@ module Cardano.Api.Internal.Fees
     -- @
     --
     -- 2. The time the network started. We can obtain it using the 'QuerySystemStart' query
-    -- defined in "Cardano.Api.Query". Let's assume we have it in the @exampleSystemStart@ variable.
+    -- defined in "Cardano.Api.Internal.Query". Let's assume we have it in the @exampleSystemStart@ variable.
     --
     -- 3. The ledger epoch info. We can obtain it by applying the 'toLedgerEpochInfo' function
     -- to the 'EraHistory' that we can obtain using the 'QueryEraHistory' query defined in
-    -- "Cardano.Api.Query". Let's assume we have it in the @exampleLedgerEpochInfo@ variable.
+    -- "Cardano.Api.Internal.Query". Let's assume we have it in the @exampleLedgerEpochInfo@ variable.
     --
     -- 4. The protocol parameters for the current era. We can get them by using the 'QueryProtocolParameters'
-    -- query defined in "Cardano.Api.Query". Let's assume we have them in the @exampleProtocolParams@ variable.
+    -- query defined in "Cardano.Api.Internal.Query". Let's assume we have them in the @exampleProtocolParams@ variable.
     --
     -- 5. For stake pool and gov actions, we will also need:
     --
@@ -247,13 +247,13 @@ module Cardano.Api.Internal.Fees
     --    For this example, I am assuming we are doing nothing like that, so we will use 'mempty' for the three.
     --
     -- 6. The part of the UTxO that we are spending. We can obtain the whole UTxO using the 'QueryUTxO' query
-    -- defined in "Cardano.Api.Query". Let's assume we have it in the @utxoToUse@ variable.
+    -- defined in "Cardano.Api.Internal.Query". Let's assume we have it in the @utxoToUse@ variable.
     --
-    -- 7. The draft 'TxBodyContent' for the transaction we want to balance. In "Cardano.Api.Tx.Body" we show
+    -- 7. The draft 'TxBodyContent' for the transaction we want to balance. In "Cardano.Api.Internal.Tx.Body" we show
     -- how to create one.
     --
     -- 8. The address where we want to send the change. We can deserialise it from its bech32 representation
-    -- by using the 'deserialiseAddress' function defined in "Cardano.Api.Address":
+    -- by using the 'deserialiseAddress' function defined in "Cardano.Api.Internal.Address":
     --
     -- @
     -- let (Just exampleChangeAddress) =

diff --git a/cardano-api/src/Cardano/Api/Internal/Tx/Body.hs b/cardano-api/src/Cardano/Api/Internal/Tx/Body.hs
@@ -33,7 +33,7 @@ module Cardano.Api.Internal.Tx.Body
     -- This hasn't changed.
     --
     -- To see how to create a transaction using the new API, see the documentation
-    -- of the "Cardano.Api.Experimental.Tx" module.
+    -- of the "Cardano.Api.Internal.Experimental.Tx" module.
     --
     -- In the following examples, we are using the following qualified modules:
     --
@@ -51,13 +51,13 @@ module Cardano.Api.Internal.Tx.Body
     -- we will see how to create a 'TxBodyContent' for a simple transaction using the API.
     --
     -- 'TxBodyContent' datatype provides lots of fields, because transactions can serve multiple
-    -- purposes, but the function 'defaultTxBodyContent' exported from 'Cardano.Api' already provides
+    -- purposes, but the function 'defaultTxBodyContent' exported from "Cardano.Api" already provides
     -- a base 'TxBodyContent' with all fields set to their default values that we can use as a starting point
     -- in order not to have to set all fields manually.
     --
     -- The 'defaultTxBodyContent' takes, as the only parameter, the 'ShelleyBasedEra' witness for the era
     -- we are working with. For example, if we are working with the 'ConwayEra', we can use 'shelleyBasedEra'
-    -- available in 'Cardano.Api', as follows:
+    -- available in "Cardano.Api", as follows:
     --
     -- @
     -- let sbe :: Api.ShelleyBasedEra Api.ConwayEra = Api.shelleyBasedEra
@@ -141,14 +141,14 @@ module Cardano.Api.Internal.Tx.Body
     -- 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.
+    -- You can see how to balance a transaction in the documentation of the "Cardano.Api.Internal.Fees" module.
 
     -- ** Creating a 'ShelleyWitnessSigningKey'
 
     -- |
     -- To sign the transaction, we need a witness. For example, a 'ShelleyWitnessSigningKey'.
     --
-    -- You can see how to create a 'ShelleyWitnessSigningKey' in the documentation of the "Cardano.Api.Tx.Sign" module.
+    -- You can see how to create a 'ShelleyWitnessSigningKey' in the documentation of the "Cardano.Api.Internal.Tx.Sign" module.
 
     -- ** Creating a transaction using the old API
 
@@ -185,7 +185,7 @@ module Cardano.Api.Internal.Tx.Body
 
     -- |
     -- If you are using the new API, you can also derive the 'ShelleyBasedEra' it from 'ConwayEra'
-    -- from 'Cardano.Api.Experimental' by using the 'convert' function:
+    -- from "Cardano.Api.Internal.Experimental" by using the 'convert' function:
     --
     -- @
     -- let era = Exp.ConwayEra