Enforce no missing docs in all crates (+ add docs that were missing)

[rust-lightning] / lightning-block-sync / src / init.rs

diff --git a/lightning-block-sync/src/init.rs b/lightning-block-sync/src/init.rs
index 24080b15acb1aa208eca0982e83f01a60117ab29..d51cd3ba606f9bd513326cc527ab677459b58b0d 100644 (file)
--- a/lightning-block-sync/src/init.rs
+++ b/lightning-block-sync/src/init.rs
@@ -1,3 +1,6 @@
+//! Utilities to assist in the initial sync required to initialize or reload Rust-Lightning objects
+//! from disk.
+
 use crate::{BlockSource, BlockSourceResult, Cache, ChainNotifier};
 use crate::poll::{ChainPoller, Validate, ValidatedBlockHeader};
 
@@ -7,6 +10,20 @@ use bitcoin::network::constants::Network;
 
 use lightning::chain;
 
+/// Returns a validated block header of the source's best chain tip.
+///
+/// Upon success, the returned header can be used to initialize [`SpvClient`]. Useful during a fresh
+/// start when there are no chain listeners to sync yet.
+///
+/// [`SpvClient`]: crate::SpvClient
+pub async fn validate_best_block_header<B: BlockSource>(block_source: &mut B) ->
+BlockSourceResult<ValidatedBlockHeader> {
+       let (best_block_hash, best_block_height) = block_source.get_best_block().await?;
+       block_source
+               .get_header(&best_block_hash, best_block_height).await?
+               .validate(best_block_hash)
+}
+
 /// Performs a one-time sync of chain listeners using a single *trusted* block source, bringing each
 /// listener's view of the chain from its paired block hash to `block_source`'s best chain tip.
 ///
@@ -101,19 +118,16 @@ use lightning::chain;
 /// }
 /// ```
 ///
-/// [`SpvClient`]: ../struct.SpvClient.html
-/// [`ChannelManager`]: ../../lightning/ln/channelmanager/struct.ChannelManager.html
-/// [`ChannelMonitor`]: ../../lightning/chain/channelmonitor/struct.ChannelMonitor.html
+/// [`SpvClient`]: crate::SpvClient
+/// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
+/// [`ChannelMonitor`]: lightning::chain::channelmonitor::ChannelMonitor
 pub async fn synchronize_listeners<B: BlockSource, C: Cache>(
        block_source: &mut B,
        network: Network,
        header_cache: &mut C,
        mut chain_listeners: Vec<(BlockHash, &mut dyn chain::Listen)>,
 ) -> BlockSourceResult<ValidatedBlockHeader> {
-       let (best_block_hash, best_block_height) = block_source.get_best_block().await?;
-       let best_header = block_source
-               .get_header(&best_block_hash, best_block_height).await?
-               .validate(best_block_hash)?;
+       let best_header = validate_best_block_header(block_source).await?;
 
        // Fetch the header for the block hash paired with each listener.
        let mut chain_listeners_with_old_headers = Vec::new();