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 16681094633

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 84.888%

---

Totals
Change from base Build 16660250657:	0.0%
Covered Lines:	6651
Relevant Lines:	7835

---

💛 - 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.

[notmandatory]

ACK c1e7fcc

Can add examples later, either way this PR adds valuable info.

[oleonardolima]

ACK c1e7fcc