f - Expand Cache documentation

Author: jkczyz

lightning-block-sync/src/lib.rs

@@ -147,18 +147,29 @@ pub trait ChainListener {
 /// The `Cache` trait defines behavior for managing a block header cache, where block headers are
 /// keyed by block hash.
 ///
-/// Used by [`ChainNotifier`] to store headers along the best chain. Implementations may define
-/// their own cache eviction policy.
+/// Used by [`ChainNotifier`] to store headers along the best chain, which is important for ensuring
+/// that blocks can be disconnected if they are no longer accessible from a block source (e.g., if
+/// the block source does not store stale forks indefinitely).
+///
+/// Implementations may define how long to retain headers such that it's unlikely they will ever be
+/// needed to disconnect a block.  In cases where block sources provide access to headers on stale
+/// forks reliably, caches may be entirely unnecessary.
 ///
 /// [`ChainNotifier`]: struct.ChainNotifier.html
 pub trait Cache {
 	/// Retrieves the block header keyed by the given block hash.
 	fn get(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader>;
 
 	/// Inserts a block header keyed by the given block hash.
+	///
+	/// Called when a block has been connected to the best chain to ensure it is available to be
+	/// disconnected later if needed.
 	fn insert(&mut self, block_hash: BlockHash, block_header: ValidatedBlockHeader);
 
 	/// Removes the block header keyed by the given block hash.
+	///
+	/// Called when a block has been disconnected from the best chain. Once disconnected, a block's
+	/// header is no longer needed and thus can be removed.
 	fn remove(&mut self, block_hash: &BlockHash) -> Option<ValidatedBlockHeader>;
 }