docs: Add doctest for Anchor implementation on BlockId

crates/chain/src/chain_data.rs

@@ -140,6 +140,9 @@ impl From<(&u32, &BlockHash)> for BlockId {
 }
 
 /// An [`Anchor`] implementation that also records the exact confirmation height of the transaction.
+/// When a transaction is anchored in [`Self::anchor_block`], it does not mean
+/// it is confirmed in that block. It just means [`Self::anchor_block`] is in the best chain and
+/// therefore our transaction is also in the best chain.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Copy, PartialOrd, Ord, core::hash::Hash)]
 #[cfg_attr(
     feature = "serde",
@@ -167,7 +170,9 @@ impl Anchor for ConfirmationHeightAnchor {
 }
 
 /// An [`Anchor`] implementation that also records the exact confirmation time and height of the
-/// transaction.
+/// transaction. When a transaction is anchored in [`Self::anchor_block`], it does not mean
+/// it is confirmed in that block. It just means [`Self::anchor_block`] is in the best chain and
+/// therefore our transaction is also in the best chain.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Copy, PartialOrd, Ord, core::hash::Hash)]
 #[cfg_attr(
     feature = "serde",

crates/chain/src/tx_data_traits.rs

@@ -44,6 +44,53 @@ impl ForEachTxOut for Transaction {
 /// assume that transaction A is also confirmed in the best chain. This does not necessarily mean
 /// that transaction A is confirmed in block B. It could also mean transaction A is confirmed in a
 /// parent block of B.
+///
+/// ```
+/// # use bdk_chain::local_chain::LocalChain;
+/// # use bdk_chain::tx_graph::TxGraph;
+/// # use bdk_chain::BlockId;
+/// # use bdk_chain::ConfirmationHeightAnchor;
+/// # use bdk_chain::example_utils::*;
+/// # use bitcoin::hashes::Hash;
+///
+/// // Initialize the local chain with two blocks.
+/// let chain = LocalChain::from_blocks(
+///     [
+///         (1, Hash::hash("first".as_bytes())),
+///         (2, Hash::hash("second".as_bytes())),
+///     ]
+///     .into_iter()
+///     .collect(),
+/// );
+///
+/// // Insert transaction into TxGraphs with different anchor types.
+/// // Insert different anchor types for the same transaction.
+/// // When using the BlockId as anchor, the anchor block is the
+/// // confirmation block of the transaction.
+/// let tx = tx_from_hex(RAW_TX_1);
+/// let mut graph_a = TxGraph::<BlockId>::default();
+/// let _ = graph_a.insert_tx(tx.clone());
+/// graph_a.insert_anchor(
+///     tx.txid(),
+///     BlockId {
+///         height: 1,
+///         hash: Hash::hash("first".as_bytes()),
+///     },
+/// );
+///
+/// let mut graph_b = TxGraph::<ConfirmationHeightAnchor>::default();
+/// let _ = graph_b.insert_tx(tx.clone());
+/// graph_b.insert_anchor(
+///     tx.txid(),
+///     ConfirmationHeightAnchor {
+///         anchor_block: BlockId {
+///             height: 2,
+///             hash: Hash::hash("second".as_bytes()),
+///         },
+///         confirmation_height: 1,
+///     },
+/// );
+/// ```
 pub trait Anchor: core::fmt::Debug + Clone + Eq + PartialOrd + Ord + core::hash::Hash {
     /// Returns the [`BlockId`] that the associated blockchain data is "anchored" in.
     fn anchor_block(&self) -> BlockId;