From: Jeffrey Czyz Date: Thu, 18 Feb 2021 20:52:25 +0000 (-0800) Subject: f - Add missing ChainPoller documentation X-Git-Url: http://git.bitcoin.ninja/?a=commitdiff_plain;h=6df54a3e2a19b9e7e1720be44af250db2094291a;p=rust-lightning f - Add missing ChainPoller documentation --- diff --git a/lightning-block-sync/src/poll.rs b/lightning-block-sync/src/poll.rs index 84ccfa7ae..3ff7606b8 100644 --- a/lightning-block-sync/src/poll.rs +++ b/lightning-block-sync/src/poll.rs @@ -8,6 +8,11 @@ use std::ops::DerefMut; /// The `Poll` trait defines behavior for polling block sources for a chain tip and retrieving /// related chain data. It serves as an adapter for `BlockSource`. +/// +/// [`ChainPoller`] adapts a single `BlockSource`, while any other implementations of `Poll` are +/// required to be built in terms of it to ensure chain data validity. +/// +/// [`ChainPoller`]: ../struct.ChainPoller.html pub trait Poll { /// Returns a chain tip in terms of its relationship to the provided chain tip. fn poll_chain_tip<'a>(&'a mut self, best_known_chain_tip: ValidatedBlockHeader) -> @@ -149,12 +154,20 @@ impl std::ops::Deref for ValidatedBlock { } } +/// The canonical `Poll` implementation used for a single `BlockSource`. +/// +/// Other `Poll` implementations must be built using `ChainPoller` as it provides the only means of +/// validating chain data. pub struct ChainPoller + Sized + Sync + Send, T: BlockSource> { block_source: B, network: Network, } impl + Sized + Sync + Send, T: BlockSource> ChainPoller { + /// Creates a new poller for the given block source. + /// + /// If the `network` parameter is mainnet, then the difficulty between blocks is checked for + /// validity. pub fn new(block_source: B, network: Network) -> Self { Self { block_source, network } }