From d69c241b5c16e78d3687146a7f0a99bd77e5abe3 Mon Sep 17 00:00:00 2001
From: "Tobin C. Harding" <me@tobin.cc>
Date: Tue, 10 Sep 2024 08:58:34 +1000
Subject: [PATCH] Improve docs on associated consts

In #3308 we added associated consts to the `Txid`, `Wtxid`, and
`OutPoint` types. During review and afterwards we realised the docs
could do with improving. Since we now want to move the types we should
do this first.

Close: #3331
---
 bitcoin/src/blockdata/transaction.rs | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/bitcoin/src/blockdata/transaction.rs b/bitcoin/src/blockdata/transaction.rs
index 4cfd65738..dcd474bf8 100644
--- a/bitcoin/src/blockdata/transaction.rs
+++ b/bitcoin/src/blockdata/transaction.rs
@@ -67,10 +67,9 @@ impl Txid {
 impl Wtxid {
     /// The `Wtxid` of a coinbase transaction.
     ///
-    /// This is used as the wTXID for the coinbase transaction when constructing blocks,
-    /// since the coinbase transaction contains a commitment to all transactions' wTXIDs
-    /// but naturally cannot commit to its own. It is not a real wTXID and should not be
-    /// used in other contexts.
+    /// This is used as the wTXID for the coinbase transaction when constructing blocks (in the
+    /// witness commitment tree) since the coinbase transaction contains a commitment to all
+    /// transactions' wTXIDs but naturally cannot commit to its own.
     pub const COINBASE: Self = Self::from_byte_array([0; 32]);
 
     /// The "all zeros" wTXID.
@@ -117,7 +116,7 @@ impl OutPoint {
     /// The `OutPoint` used in a coinbase prevout.
     ///
     /// This is used as the dummy input for coinbase transactions because they don't have any
-    /// previous outputs. This is not a real outpoint and should not be used in any other contexts.
+    /// previous outputs. In other words, does not point to a real transaction.
     pub const COINBASE_PREVOUT: Self = Self { txid: Txid::COINBASE_PREVOUT, vout: u32::MAX };
 
     /// Creates a new [`OutPoint`].