docs: Update stake merging documentation (#15489)

* Update stake merging documentation

* Integrate review feedback

* Integrate review feedback in comment too

docs/src/staking/stake-accounts.md

@@ -41,7 +41,7 @@ The *stake authority* is used to sign transactions for the following operations:
  - Deactivating the stake delegation
  - Splitting the stake account, creating a new stake account with a portion of the
  funds in the first account
- - Merging two undelegated stake accounts into one
+ - Merging two stake accounts into one
  - Setting a new stake authority
 
 The *withdraw authority* signs transactions for the following:
@@ -76,8 +76,21 @@ with token balances of your choosing.
 The same stake and withdraw authorities can be assigned to multiple
 stake accounts.
 
-Two stake accounts that are not delegated and that have the same authorities
-and lockup can be merged into a single resulting stake account.
+#### Merging stake accounts
+Two stake accounts that have the same authorities and lockup can be merged into
+a single resulting stake account. A merge is possible between two stakes in the
+following states with no additional conditions:
+
+* two deactivated stakes
+* an inactive stake into an activating stake during its activation epoch
+
+For the following cases, the voter pubkey and vote credits observed must match:
+
+* two activated stakes
+* two activating accounts that share an activation epoch, during the activation epoch
+
+All other combinations of stake states will fail to merge, including all "transient"
+states, where a stake is activating or deactivating with a non-zero effective stake.
 
 #### Delegation Warmup and Cooldown
 When a stake account is delegated, or a delegation is deactivated, the operation

programs/stake/src/stake_instruction.rs

@@ -131,8 +131,23 @@ pub enum StakeInstruction {
     ///   1. [SIGNER] Lockup authority
     SetLockup(LockupArgs),
 
-    /// Merge two stake accounts. Both accounts must be deactivated and have identical lockup and
-    /// authority keys.
+    /// Merge two stake accounts.
+    ///
+    /// Both accounts must have identical lockup and authority keys. A merge
+    /// is possible between two stakes in the following states with no additional
+    /// conditions:
+    ///
+    /// * two deactivated stakes
+    /// * an inactive stake into an activating stake during its activation epoch
+    ///
+    /// For the following cases, the voter pubkey and vote credits observed must match:
+    ///
+    /// * two activated stakes
+    /// * two activating accounts that share an activation epoch, during the activation epoch
+    ///
+    /// All other combinations of stake states will fail to merge, including all
+    /// "transient" states, where a stake is activating or deactivating with a
+    /// non-zero effective stake.
     ///
     /// # Account references
     ///   0. [WRITE] Destination stake account for the merge

programs/stake/src/stake_state.rs

@@ -678,7 +678,7 @@ impl Stake {
     ///   * staker_rewards to be distributed
     ///   * voter_rewards to be distributed
     ///   * new value for credits_observed in the stake
-    //  returns None if there's no payout or if any deserved payout is < 1 lamport
+    /// returns None if there's no payout or if any deserved payout is < 1 lamport
     pub fn calculate_rewards(
         &self,
         point_value: &PointValue,