docs(wallet): expand docs for apply_evicted_txs

[ValuedMammal]

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:

• I followed the contribution guidelines

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
• I'm linking the issue being fixed by this PR

[coveralls]

Pull Request Test Coverage Report for Build 16274314345

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 44 unchanged lines in 1 file lost coverage.
• Overall coverage decreased (-0.04%) to 84.69%

---

Files with Coverage Reduction	New Missed Lines	%
wallet/src/wallet/persisted.rs	44	36.16%

Totals
Change from base Build 16052072493:	-0.04%
Covered Lines:	6577
Relevant Lines:	7766

---

💛 - Coveralls

[tvpeter]

Thank you Mammal for the excellent documentation.

ACK 9284767

I left a suggestion for including an example if it won't become too lengthy.

[tvpeter]

I think it would be great to also include an example here:

Suggested change

	/// [`start_sync_with_revealed_spks`]: Wallet::start_sync_with_revealed_spks
	/// [`start_sync_with_revealed_spks`]: Wallet::start_sync_with_revealed_spks
	/// ## Example
	///
	/// ```rust
	/// use bdk_wallet::{Wallet, bitcoin::Txid};
	/// use std::collections::HashSet;
	///
	/// let unconfirmed_txids: HashSet<Txid> = wallet
	/// .transactions()
	/// .filter(|tx| tx.chain_position.is_unconfirmed())
	/// .map(|tx| tx.tx_node.txid)
	/// .collect();
	///
	/// let mut evicted_txs = Vec::new();
	/// for txid in unconfirmed_txids {
	/// let tx_node = wallet.tx_graph().full_txs().find(|tx| tx.txid == txid);
	/// let wallet_tx = wallet.get_tx(txid);
	/// let is_evicted = wallet_tx.map_or(true, |tx| {
	/// !tx.chain_position.is_unconfirmed() && !tx.chain_position.is_confirmed()
	/// });
	/// if is_evicted {
	/// let last_seen = tx_node.map_or(0, |tx| tx.last_seen.unwrap_or(0));
	/// evicted_txs.push((txid, last_seen));
	/// }
	/// }
	///
	/// if !evicted_txs.is_empty() {
	/// wallet.apply_evicted_txs(evicted_txs)?;
	/// wallet.persist(&mut db)?;
	/// }

[notmandatory]

It's not clear to me if or when a user needs to use this function. Don't the bdk_* chain clients already evict tx when they notice it missing from the mempool?

[ValuedMammal]

@tvpeter @notmandatory One usage example that I know of is in the example_wallet_rpc.