Update documentation

* Add `warn(missing_docs)` for `bdk_wallet` and `bdk_chain`.
* Add missing documentation.
* Remove `LocalChain::heights` method.
* Remove old TODOs.

crates/chain/src/chain_data.rs

@@ -21,6 +21,7 @@ impl<A> ChainPosition<A> {
 }
 
 impl<A: Clone> ChainPosition<&A> {
+    /// Maps a [`ChainPosition<&A>`] into a [`ChainPosition<A>`] by cloning the contents.
     pub fn cloned(self) -> ChainPosition<A> {
         match self {
             ChainPosition::Confirmed(a) => ChainPosition::Confirmed(a.clone()),
@@ -30,6 +31,7 @@ impl<A: Clone> ChainPosition<&A> {
 }
 
 impl<A: Anchor> ChainPosition<A> {
+    /// Determines the upper bound of the confirmation height.
     pub fn confirmation_height_upper_bound(&self) -> Option<u32> {
         match self {
             ChainPosition::Confirmed(a) => Some(a.confirmation_height_upper_bound()),
@@ -46,15 +48,27 @@ impl<A: Anchor> ChainPosition<A> {
     serde(crate = "serde_crate")
 )]
 pub enum ConfirmationTime {
-    Confirmed { height: u32, time: u64 },
-    Unconfirmed { last_seen: u64 },
+    /// The confirmed variant.
+    Confirmed {
+        /// Confirmation height.
+        height: u32,
+        /// Confirmation time in unix seconds.
+        time: u64,
+    },
+    /// The unconfirmed variant.
+    Unconfirmed {
+        /// The last-seen timestamp in unix seconds.
+        last_seen: u64,
+    },
 }
 
 impl ConfirmationTime {
+    /// Construct an unconfirmed variant using the given `last_seen` time in unix seconds.
     pub fn unconfirmed(last_seen: u64) -> Self {
         Self::Unconfirmed { last_seen }
     }
 
+    /// Returns whether [`ConfirmationTime`] is the confirmed variant.
     pub fn is_confirmed(&self) -> bool {
         matches!(self, Self::Confirmed { .. })
     }
@@ -154,8 +168,9 @@ impl Anchor for ConfirmationHeightAnchor {
 pub struct ConfirmationTimeAnchor {
     /// The anchor block.
     pub anchor_block: BlockId,
-
+    /// The confirmation height of the chain data being anchored.
     pub confirmation_height: u32,
+    /// The confirmation time of the chain data being anchored.
     pub confirmation_time: u64,
 }
 

crates/chain/src/indexed_tx_graph.rs

@@ -1,3 +1,7 @@
+//! Contains the [`IndexedTxGraph`] structure and associated types.
+//!
+//! This is essentially a [`TxGraph`] combined with an indexer.
+
 use alloc::vec::Vec;
 use bitcoin::{OutPoint, Transaction, TxOut};
 

crates/chain/src/lib.rs

@@ -17,18 +17,23 @@
 //!    cache or how you fetch it.
 //!
 //! [Bitcoin Dev Kit]: https://bitcoindevkit.org/
+
 #![no_std]
+#![warn(missing_docs)]
+
 pub use bitcoin;
 mod spk_txout_index;
 pub use spk_txout_index::*;
 mod chain_data;
 pub use chain_data::*;
 pub mod indexed_tx_graph;
+pub use indexed_tx_graph::IndexedTxGraph;
 pub mod keychain;
 pub mod local_chain;
 mod tx_data_traits;
 pub mod tx_graph;
 pub use tx_data_traits::*;
+pub use tx_graph::TxGraph;
 mod chain_oracle;
 pub use chain_oracle::*;
 mod persist;

crates/chain/src/local_chain.rs

@@ -1,6 +1,8 @@
+//! The [`LocalChain`] is a local implementation of [`ChainOracle`].
+
 use core::convert::Infallible;
 
-use alloc::collections::{BTreeMap, BTreeSet};
+use alloc::collections::BTreeMap;
 use bitcoin::BlockHash;
 
 use crate::{BlockId, ChainOracle};
@@ -59,6 +61,7 @@ impl From<BTreeMap<u32, BlockHash>> for LocalChain {
 }
 
 impl LocalChain {
+    /// Contruct a [`LocalChain`] from a list of [`BlockId`]s.
     pub fn from_blocks<B>(blocks: B) -> Self
     where
         B: IntoIterator<Item = BlockId>,
@@ -73,6 +76,7 @@ impl LocalChain {
         &self.blocks
     }
 
+    /// Get the chain tip.
     pub fn tip(&self) -> Option<BlockId> {
         self.blocks
             .iter()
@@ -158,6 +162,9 @@ impl LocalChain {
         Ok(changeset)
     }
 
+    /// Derives a [`ChangeSet`] that assumes that there are no preceding changesets.
+    ///
+    /// The changeset returned will record additions of all blocks included in [`Self`].
     pub fn initial_changeset(&self) -> ChangeSet {
         self.blocks
             .iter()
@@ -165,10 +172,6 @@ impl LocalChain {
             .collect()
     }
 
-    pub fn heights(&self) -> BTreeSet<u32> {
-        self.blocks.keys().cloned().collect()
-    }
-
     /// Insert a block of [`BlockId`] into the [`LocalChain`].
     ///
     /// # Error
@@ -225,8 +228,11 @@ impl std::error::Error for UpdateNotConnectedError {}
 /// Represents a failure when trying to insert a checkpoint into [`LocalChain`].
 #[derive(Clone, Debug, PartialEq)]
 pub struct InsertBlockNotMatchingError {
+    /// The checkpoints' height.
     pub height: u32,
+    /// Original checkpoint's block hash.
     pub original_hash: BlockHash,
+    /// Update checkpoint's block hash.
     pub update_hash: BlockHash,
 }
 

crates/chain/src/tx_graph.rs

@@ -983,9 +983,13 @@ impl<A: Anchor> TxGraph<A> {
 )]
 #[must_use]
 pub struct Additions<A = ()> {
+    /// Added transactions.
     pub txs: BTreeSet<Transaction>,
+    /// Added txouts.
     pub txouts: BTreeMap<OutPoint, TxOut>,
+    /// Added anchors.
     pub anchors: BTreeSet<(A, Txid)>,
+    /// Added last-seen unix timestamps of transactions.
     pub last_seen: BTreeMap<Txid, u64>,
 }