Merge bitcoindevkit#1680: docs(wallet): reword the `next_unused_addre…

…ss` doc

b39cf08 docs(wallet): reword the `next_unused_address` doc (Leonardo Lima)

Pull request description:

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

  ### Description

  Adds an example on what `used` stands for, and make it explicit that it
  has the same behavior as `Wallet::reveal_next_address` in the scenario
  where all previously revealed addresses have been used.

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

  ### Notes to the reviewers

  Is there any other behavior of `next_unused_address` we'd need to make clear through documentation ?

  <!-- 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

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

  - Improve the `Wallet::next_unused_address` documentation to better describe expected behavior/usage.

  ### 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

  #### 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

ACKs for top commit:
  notmandatory:
    ACK b39cf08
  ValuedMammal:
    ACK b39cf08

Tree-SHA512: af4e912db9b3283527c00ed91a72c1c01f1dd6d8889cf345c6347e77152f7e3aadc93c7040e4283411e078b3394fb46f1b4d7f6f872f39d2219e03f242ee1130

crates/wallet/src/wallet/mod.rs

@@ -732,10 +732,10 @@ impl Wallet {
     }
 
     /// Get the next unused address for the given `keychain`, i.e. the address with the lowest
-    /// derivation index that hasn't been used.
+    /// derivation index that hasn't been used in a transaction.
     ///
-    /// This will attempt to derive and reveal a new address if no newly revealed addresses
-    /// are available. See also [`reveal_next_address`](Self::reveal_next_address).
+    /// This will attempt to reveal a new address if all previously revealed addresses have
+    /// been used, in which case the returned address will be the same as calling [`Wallet::reveal_next_address`].
     ///
     /// **WARNING**: To avoid address reuse you must persist the changes resulting from one or more
     /// calls to this method before closing the wallet. See [`Wallet::reveal_next_address`].