Update documentation

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

Author: evanlinjin

crates/bdk/src/lib.rs

@@ -1,5 +1,7 @@
 #![doc = include_str!("../README.md")]
 #![no_std]
+#![warn(missing_docs)]
+
 #[cfg(feature = "std")]
 #[macro_use]
 extern crate std;

crates/bdk/src/wallet/mod.rs

@@ -21,12 +21,12 @@ use alloc::{
 };
 pub use bdk_chain::keychain::Balance;
 use bdk_chain::{
-    indexed_tx_graph::{IndexedAdditions, IndexedTxGraph},
+    indexed_tx_graph::IndexedAdditions,
     keychain::{KeychainTxOutIndex, LocalChangeSet, LocalUpdate},
     local_chain::{self, LocalChain, UpdateNotConnectedError},
     tx_graph::{CanonicalTx, TxGraph},
-    Append, BlockId, ChainPosition, ConfirmationTime, ConfirmationTimeAnchor, FullTxOut, Persist,
-    PersistBackend,
+    Append, BlockId, ChainPosition, ConfirmationTime, ConfirmationTimeAnchor, FullTxOut,
+    IndexedTxGraph, Persist, PersistBackend,
 };
 use bitcoin::consensus::encode::serialize;
 use bitcoin::secp256k1::Secp256k1;
@@ -88,15 +88,15 @@ pub struct Wallet<D = ()> {
     change_signers: Arc<SignersContainer>,
     chain: LocalChain,
     indexed_graph: IndexedTxGraph<ConfirmationTimeAnchor, KeychainTxOutIndex<KeychainKind>>,
-    persist: Persist<D, ChangeSet>, // [TODO] Use a different `ChangeSet`
+    persist: Persist<D, ChangeSet>,
     network: Network,
     secp: SecpCtx,
 }
 
 /// The update to a [`Wallet`] used in [`Wallet::apply_update`]. This is usually returned from blockchain data sources.
 pub type Update = LocalUpdate<KeychainKind, ConfirmationTimeAnchor>;
 
-// /// The changeset produced internally by applying an update.
+/// The changeset produced internally by [`Wallet`] when mutated.
 pub type ChangeSet = LocalChangeSet<KeychainKind, ConfirmationTimeAnchor>;
 
 /// The address index selection strategy to use to derived an address from the wallet's external
@@ -184,10 +184,15 @@ where
     }
 }
 
+/// An error that may occur when inserting a transaction into [`Wallet`].
 #[derive(Debug)]
 pub enum InsertTxError {
+    /// The error variant that occurs when the caller attempts to insert a transaction with a
+    /// confirmation height that is greater than the internal chain tip.
     ConfirmationHeightCannotBeGreaterThanTip {
+        /// The internal chain's tip height.
         tip_height: Option<u32>,
+        /// The introduced transaction's confirmation height.
         tx_height: u32,
     },
 }

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,17 +162,16 @@ 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()
             .map(|(&height, &hash)| (height, Some(hash)))
             .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>,
 }
 

crates/electrum/src/electrum_ext.rs

@@ -236,7 +236,6 @@ impl ElectrumExt<ConfirmationHeightAnchor> for Client {
 
             populate_with_txids(self, anchor_block, &mut update, &mut txids.iter().cloned())?;
 
-            // [TODO] cache transactions to reduce bandwidth
             let _txs = populate_with_outpoints(
                 self,
                 anchor_block,