docs: Update stake merging documentation (#15489)

* Update stake merging documentation

* Integrate review feedback

* Integrate review feedback in comment too

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,