From: Jeffrey Czyz <jkczyz@gmail.com>
Date: Thu, 18 Feb 2021 20:52:25 +0000 (-0800)
Subject: f - Add missing ChainPoller documentation
X-Git-Url: http://git.bitcoin.ninja/index.cgi?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 84ccfa7a..3ff7606b 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<B: DerefMut<Target=T> + Sized + Sync + Send, T: BlockSource> {
 	block_source: B,
 	network: Network,
 }
 
 impl<B: DerefMut<Target=T> + Sized + Sync + Send, T: BlockSource> ChainPoller<B, T> {
+	/// 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 }
 	}