From: 志宇 <hello@evanlinjin.me>
Date: Thu, 5 Mar 2026 06:03:40 +0000 (+0000)
Subject: docs(core): address review feedback on docs and tests
X-Git-Url: http://internal-gitweb-vhost/?a=commitdiff_plain;h=031b30fb3fbc19894c85dccc0d6a5515442e5bce;p=bdk

docs(core): address review feedback on docs and tests

Address suggestions by @nymius:
- Add `Returns` and `Errors` doc sections to `CheckPoint::from_blocks`
- Add test assertions for chain integrity after failed push and chain
  length after successful push

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---

diff --git a/crates/core/src/checkpoint.rs b/crates/core/src/checkpoint.rs
index 842949b4..2a4944a5 100644
--- a/crates/core/src/checkpoint.rs
+++ b/crates/core/src/checkpoint.rs
@@ -283,9 +283,15 @@ where
 
     /// Construct from an iterator of block data.
     ///
+    /// # Returns
+    ///
+    /// Returns the checkpoint chain tip on success.
+    ///
+    /// # Errors
+    ///
     /// Returns `Err(None)` if `blocks` doesn't yield any data. If the blocks are not in ascending
-    /// height order, or there are any `prev_blockhash` mismatches, then returns an `Err(..)`
-    /// containing the last checkpoint that would have been extended.
+    /// height order, or there are any `prev_blockhash` mismatches, then returns `Err(Some(..))`
+    /// containing the last checkpoint that was successfully extended.
     pub fn from_blocks(blocks: impl IntoIterator<Item = (u32, D)>) -> Result<Self, Option<Self>> {
         let mut blocks = blocks.into_iter();
         let (height, data) = blocks.next().ok_or(None)?;
diff --git a/crates/core/tests/test_checkpoint.rs b/crates/core/tests/test_checkpoint.rs
index f43bbd5a..fb5048e0 100644
--- a/crates/core/tests/test_checkpoint.rs
+++ b/crates/core/tests/test_checkpoint.rs
@@ -456,6 +456,10 @@ fn checkpoint_push_fails_conflicting_prev_blockhash() {
         result.unwrap_err().eq_ptr(&cp),
         "should return self on error"
     );
+
+    // Verify the original checkpoint at 100 is still intact
+    assert_eq!(cp.height(), 100);
+    assert_eq!(cp.hash(), hash!("block_100"));
 }
 
 /// Test that push succeeds when prev_blockhash matches self's hash for contiguous height.
@@ -485,6 +489,11 @@ fn checkpoint_push_succeeds_matching_prev_blockhash() {
     let new_cp = result.unwrap();
     assert_eq!(new_cp.height(), 101);
     assert_eq!(new_cp.hash(), hash!("block_101"));
+    assert_eq!(
+        new_cp.iter().count(),
+        2,
+        "should have 2 checkpoints (100, 101)"
+    );
 }
 
 /// Test that push creates a placeholder for non-contiguous heights with prev_blockhash.