consensus: an editing pass on the addTx Haddock

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Mempool/API.hs

@@ -96,31 +96,30 @@ data Mempool m blk = Mempool {
       --
       -- The new transaction provided will be validated, /in order/, against
       -- the ledger state obtained by applying all the transactions already in
-      -- the Mempool to it. Transactions which are found to be invalid, with
-      -- respect to the ledger state, are dropped, whereas valid transactions
-      -- are added to the mempool.
+      -- the mempool. Transactions which are found to be invalid are dropped,
+      -- whereas valid transactions are added to the mempool.
       --
-      -- Note that transactions that are invalid, with respect to the ledger
-      -- state, will /never/ be added to the mempool. However, it is possible
-      -- that, at a given point in time, transactions which were once valid
-      -- but are now invalid, with respect to the current ledger state, could
-      -- exist within the mempool until they are revalidated and dropped from
-      -- the mempool via a call to 'syncWithLedger' or by the background
-      -- thread that watches the ledger for changes.
+      -- Note that transactions that are invalid will /never/ be added to the
+      -- mempool. However, it is possible that, at a given point in time,
+      -- transactions which were valid in an older ledger state but are invalid
+      -- in the current ledger state, could exist within the mempool until they
+      -- are revalidated and dropped from the mempool via a call to
+      -- 'syncWithLedger' or by the background thread that watches the ledger
+      -- for changes.
       --
-      -- This action returns one of two results
+      -- This action returns one of two results.
       --
       --  * A 'MempoolTxAdded' value if the transaction provided was found to
-      --    be valid. This transactions is now in the Mempool.
+      --    be valid. This transactions is now in the mempool.
       --
       --  * A 'MempoolTxRejected' value if the transaction provided was found
       --    to be invalid, along with its accompanying validation errors. This
-      --    transactions is not in the Mempool.
+      --    transactions is not in the mempool.
       --
       -- Note that this is a blocking action. It will block until the
       -- transaction fits into the mempool. This includes transactions that
       -- turn out to be invalid: the action waits for there to be space for
-      -- the transaction before it gets validated.
+      -- the transaction before validation is attempted.
       --
       -- Note that it is safe to use this from multiple threads concurrently.
       --
@@ -131,10 +130,6 @@ data Mempool m blk = Mempool {
       -- > processed <- addTx wti txs
       -- > prj processed == tx
       --
-      -- Note that previously valid transaction that are now invalid with
-      -- respect to the current ledger state are dropped from the mempool, but
-      -- are not part of the first returned list (nor the second).
-      --
       -- In principle it is possible that validation errors are transient; for
       -- example, it is possible that a transaction is rejected because one of
       -- its inputs is not /yet/ available in the UTxO (the transaction it
@@ -156,7 +151,6 @@ data Mempool m blk = Mempool {
       -- As long as we keep the mempool entirely in-memory this could live in
       -- @STM m@; we keep it in @m@ instead to leave open the possibility of
       -- persistence.
-      --
       addTx      :: AddTxOnBehalfOf
                  -> GenTx blk
                  -> m (MempoolAddTxResult blk)