From f3c463a7135c38cdc861a32ddcbcc6f837cacf4a Mon Sep 17 00:00:00 2001
From: Daniela Brozzoni <danielabrozzoni@protonmail.com>
Date: Wed, 8 May 2024 15:45:45 +0200
Subject: [PATCH] doc: Clarification for multiple K same descriptor

---
 crates/chain/src/keychain/txout_index.rs | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/crates/chain/src/keychain/txout_index.rs b/crates/chain/src/keychain/txout_index.rs
index c80913a2b..74e514598 100644
--- a/crates/chain/src/keychain/txout_index.rs
+++ b/crates/chain/src/keychain/txout_index.rs
@@ -168,11 +168,17 @@ const DEFAULT_LOOKAHEAD: u32 = 25;
 /// this is useful in case a user unassigns a keychain from a descriptor and after some time
 /// assigns it again.
 ///
-/// Additionally, although a keychain can only be assigned to one descriptor, different keychains
-/// can be assigned to the same descriptor. When a method returns spks/outpoints that is associated
-/// with a descriptor, it may be associated with multiple keychain variants. The keychain variant
-/// with the higher rank will be returned. Rank is determined by the [`Ord`] implementation of the
-/// keychain type. Earlier keychain variants have higher rank.
+/// # Different keychains assigned to one descriptor
+///
+/// Although a keychain can only be assigned to one descriptor, different keychains
+/// can be assigned to the same descriptor. This is not recommended.
+///
+/// If multiple keycahins are assigned to the same descriptor:
+/// 1. Methods that take in a keychain, such as [`KeychainTxOutIndex::reveal_next_spk`],
+/// will work normally when either keychain is passed in.
+/// 2. Methods that return a keychain, such as [`KeychainTxOutIndex::outpoints`] will
+/// return only the keychain variant with the highest rank.
+/// Rank is determined by the [`Ord`] implementation of the keychain type.
 ///
 /// [`Ord`]: core::cmp::Ord
 /// [`SpkTxOutIndex`]: crate::spk_txout_index::SpkTxOutIndex