doc(wallet): improve docs for single descriptor usage

crates/wallet/src/wallet/mod.rs

@@ -559,7 +559,7 @@ impl Wallet {
     ///
     /// For non-wildcard descriptors this returns the same address at every provided index.
     ///
-    /// # Panics (TODO: document panics for address methods)
+    /// # Panics
     ///
     /// This panics when the caller requests for an address of derivation index greater than the
     /// [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) max index.
@@ -589,7 +589,9 @@ impl Wallet {
     /// This will increment the keychain's derivation index. If the keychain's descriptor doesn't
     /// contain a wildcard or every address is already revealed up to the maximum derivation
     /// index defined in [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki),
-    /// then the last revealed address will be returned.
+    /// then the last revealed address will be returned. Note that if this wallet only has one
+    /// keychain, then by default this method and similar ones will only derive addresses using
+    /// the external keychain.
     ///
     /// **WARNING**: To avoid address reuse you must persist the changes resulting from one or more
     /// calls to this method before closing the wallet. For example:
@@ -709,6 +711,8 @@ impl Wallet {
     /// Note if the returned iterator is empty you can reveal more addresses
     /// by using [`reveal_next_address`](Self::reveal_next_address) or
     /// [`reveal_addresses_to`](Self::reveal_addresses_to).
+    ///
+    /// Returns an empty iterator if the provided keychain doesn't exist.
     pub fn list_unused_addresses(
         &self,
         keychain: KeychainKind,
@@ -1073,9 +1077,8 @@ impl Wallet {
 
     /// Set the keymap for a given keychain.
     ///
-    /// Note this is a no-op if the given keychain is not assigned a descriptor
-    /// because we won't know the context (segwit, taproot, etc) in which to create
-    /// signatures.
+    /// Note this is a no-op if the given keychain has no descriptor because we won't
+    /// know the context (segwit, taproot, etc) in which to create signatures.
     pub fn set_keymap(&mut self, keychain: KeychainKind, keymap: KeyMap) {
         let wallet_signers = match keychain {
             KeychainKind::External => Arc::make_mut(&mut self.signers),
@@ -1763,10 +1766,13 @@ impl Wallet {
     }
 
     /// Returns the descriptor used to create addresses for a particular `keychain`.
+    ///
     /// It's the "public" version of the wallet's descriptor, meaning a new descriptor that has
     /// the same structure but with the all secret keys replaced by their corresponding public key.
-    ///
     /// This can be used to build a watch-only version of a wallet.
+    ///
+    /// If this wallet has no internal keychain, then it returns the descriptor of the
+    /// external keychain.
     pub fn public_descriptor(&self, keychain: KeychainKind) -> &ExtendedDescriptor {
         self.indexed_graph
             .index

crates/wallet/src/wallet/tx_builder.rs

@@ -481,7 +481,8 @@ impl<'a, Cs> TxBuilder<'a, Cs> {
     /// Do not spend change outputs
     ///
     /// This effectively adds all the change outputs to the "unspendable" list. See
-    /// [`TxBuilder::unspendable`].
+    /// [`TxBuilder::unspendable`]. This method assumes the presence of an internal
+    /// keychain, otherwise it has no effect.
     pub fn do_not_spend_change(&mut self) -> &mut Self {
         self.params.change_policy = ChangeSpendPolicy::ChangeForbidden;
         self
@@ -490,14 +491,16 @@ impl<'a, Cs> TxBuilder<'a, Cs> {
     /// Only spend change outputs
     ///
     /// This effectively adds all the non-change outputs to the "unspendable" list. See
-    /// [`TxBuilder::unspendable`].
+    /// [`TxBuilder::unspendable`]. This method assumes the presence of an internal
+    /// keychain, otherwise it has no effect.
     pub fn only_spend_change(&mut self) -> &mut Self {
         self.params.change_policy = ChangeSpendPolicy::OnlyChange;
         self
     }
 
     /// Set a specific [`ChangeSpendPolicy`]. See [`TxBuilder::do_not_spend_change`] and
-    /// [`TxBuilder::only_spend_change`] for some shortcuts.
+    /// [`TxBuilder::only_spend_change`] for some shortcuts. This method assumes the presence
+    /// of an internal keychain, otherwise it has no effect.
     pub fn change_policy(&mut self, change_policy: ChangeSpendPolicy) -> &mut Self {
         self.params.change_policy = change_policy;
         self