Merge #1806: fix(docs): merge_chains outdated documentation

5647241 fix(docs): `merge_chains` documentation (Leonardo Lima)

Pull request description:

  <!-- You can erase any parts of this template not applicable to your Pull Request. -->

  ### Description

  It's a minor documentation fix, as reported during the audit and referenced in bitcoindevkit/bdk_wallet#59.

  <!-- Describe the purpose of this PR, what's being adding and/or fixed -->

  ### Notes to the reviewers

  I'm unsure if anything else / any other explanation should be included in the documentation. Let me know if you think more context should be added to it.

  <!-- In this section you can include notes directed to the reviewers, like explaining why some parts
  of the PR were done in a specific way -->

  ### Changelog notice

  - Update `bdk_chain::local_chain::merge_chains` documentation.

  <!-- Notice the release manager should include in the release tag message changelog -->
  <!-- See https://keepachangelog.com/en/1.0.0/ for examples -->

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

ACKs for top commit:
  evanlinjin:
    self-ACK 5647241

Tree-SHA512: a70a67eab9c8fa0c60a674efed82ddeb9bc9b69763fefaa38a9058d7a1e67c06045c3e5a31aaf0d48c0a599d03bac0a3a86530cc250acefea9497572c01b8b0e

Author: evanlinjin

crates/chain/src/local_chain.rs

@@ -545,31 +545,46 @@ impl std::error::Error for ApplyHeaderError {}
 
 /// Applies `update_tip` onto `original_tip`.
 ///
-/// On success, a tuple is returned `(changeset, can_replace)`. If `can_replace` is true, then the
-/// `update_tip` can replace the `original_tip`.
+/// On success, a tuple is returned ([`CheckPoint`], [`ChangeSet`]).
+///
+/// # Errors
+///
+/// [`CannotConnectError`] occurs when the `original_tip` and `update_tip` chains are disjoint:
+///
+/// - If no point of agreement is found between the update and original chains.
+/// - A point of agreement is found but the update is ambiguous above the point of agreement (a.k.a.
+///   the update and original chain both have a block above the point of agreement, but their
+///   heights do not overlap).
+/// - The update attempts to replace the genesis block of the original chain.
 fn merge_chains(
     original_tip: CheckPoint,
     update_tip: CheckPoint,
 ) -> Result<(CheckPoint, ChangeSet), CannotConnectError> {
     let mut changeset = ChangeSet::default();
+
     let mut orig = original_tip.iter();
     let mut update = update_tip.iter();
+
     let mut curr_orig = None;
     let mut curr_update = None;
+
     let mut prev_orig: Option<CheckPoint> = None;
     let mut prev_update: Option<CheckPoint> = None;
+
     let mut point_of_agreement_found = false;
+
     let mut prev_orig_was_invalidated = false;
+
     let mut potentially_invalidated_heights = vec![];
 
     // If we can, we want to return the update tip as the new tip because this allows checkpoints
     // in multiple locations to keep the same `Arc` pointers when they are being updated from each
-    // other using this function. We can do this as long as long as the update contains every
+    // other using this function. We can do this as long as the update contains every
     // block's height of the original chain.
     let mut is_update_height_superset_of_original = true;
 
     // To find the difference between the new chain and the original we iterate over both of them
-    // from the tip backwards in tandem. We always dealing with the highest one from either chain
+    // from the tip backwards in tandem. We are always dealing with the highest one from either chain
     // first and move to the next highest. The crucial logic is applied when they have blocks at the
     // same height.
     loop {