Merge #270: docs(wallet): expand docs for apply_evicted_txs

05e1f4a docs(wallet): expand docs for `apply_evicted_txs` (valued mammal)

Pull request description:

  ### Description

  Expand the API docs for `Wallet::apply_evicted_txs`.

  This can help to fix #254 by having a section explaining the logic of mempool evictions.

  ### Changelog notice

  ### Checklists

  #### All Submissions:

  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)

  #### New Features:

  * [ ] I've added tests for the new feature
  * [ ] I've added docs for the new feature

  #### Bugfixes:

  * [ ] ~~This pull request breaks the existing API~~
  * [ ] I've added tests to reproduce the issue which are now passing
  * [x] I'm linking the issue being fixed by this PR

Top commit has no ACKs.

Tree-SHA512: cf2f067ca2a962c891569cd9a9268c25dc693365e1c2325361b02f50547c1e0afd489a9d228717156934f82b605f2cd9e2e6e5f2b12c1445334961f6c5bb6302

Author: notmandatory

wallet/src/wallet/mod.rs

@@ -2489,13 +2489,44 @@ impl Wallet {
         self.stage.merge(indexed_graph_changeset.into());
     }
 
-    /// Apply evictions of the given txids with their associated timestamps.
+    /// Apply evictions of the given transaction IDs with their associated timestamps.
     ///
-    /// This means that any pending unconfirmed tx in this set will no longer be canonical by
-    /// default. Note that an evicted tx can become canonical if it is later seen again or
-    /// observed on-chain.
+    /// This function is used to mark specific unconfirmed transactions as evicted from the mempool.
+    /// Eviction means that these transactions are not considered canonical by default, and will
+    /// no longer be part of the wallet's [`transactions`] set. This can happen for example when
+    /// a transaction is dropped from the mempool due to low fees or conflicts with another
+    /// transaction.
     ///
-    /// This stages the changes which need to be persisted.
+    /// Only transactions that are currently unconfirmed and canonical are considered for eviction.
+    /// Transactions that are not relevant to the wallet are ignored. Note that an evicted
+    /// transaction can become canonical again if it is later observed on-chain or seen in the
+    /// mempool with a higher priority (e.g., due to a fee bump).
+    ///
+    /// ## Parameters
+    ///
+    /// `evicted_txs`: An iterator of `(Txid, u64)` tuples, where:
+    /// - `Txid`: The transaction ID of the transaction to be evicted.
+    /// - `u64`: The timestamp indicating when the transaction was evicted from the mempool. This
+    ///   will usually correspond to the time of the latest chain sync. See docs for
+    ///   [`start_sync_with_revealed_spks`].
+    ///
+    /// ## Notes
+    ///
+    /// - Not all blockchain backends support automatic mempool eviction handling - this method may
+    ///   be used in such cases. It can also be used to negate the effect of
+    ///   [`apply_unconfirmed_txs`] for a particular transaction without the need for an additional
+    ///   sync.
+    /// - The changes are staged in the wallet's internal state and must be persisted to ensure they
+    ///   are retained across wallet restarts. Use [`Wallet::take_staged`] to retrieve the staged
+    ///   changes and persist them to your database of choice.
+    /// - Evicted transactions are removed from the wallet's canonical transaction set, but the data
+    ///   remains in the wallet's internal transaction graph for historical purposes.
+    /// - Ensure that the timestamps provided are accurate and monotonically increasing, as they
+    ///   influence the wallet's canonicalization logic.
+    ///
+    /// [`transactions`]: Wallet::transactions
+    /// [`apply_unconfirmed_txs`]: Wallet::apply_unconfirmed_txs
+    /// [`start_sync_with_revealed_spks`]: Wallet::start_sync_with_revealed_spks
     pub fn apply_evicted_txs(&mut self, evicted_txs: impl IntoIterator<Item = (Txid, u64)>) {
         let chain = &self.chain;
         let canon_txids: Vec<Txid> = self