chore: fix stale doc comments

clarity/src/vm/database/structures.rs

@@ -544,7 +544,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V2 PoX.
+    /// Returns `Err` if `self` was not locked by V2 PoX.
     pub fn increase_lock_v2(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {
@@ -763,7 +763,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V3 PoX.
+    /// Returns `Err` if `self` was not locked by V3 PoX.
     pub fn increase_lock_v3(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {
@@ -889,7 +889,7 @@ impl<'db, 'conn> STXBalanceSnapshot<'db, 'conn> {
     }
 
     /// Increase the account's current lock to `new_total_locked`.
-    /// Panics if `self` was not locked by V3 PoX.
+    /// Panics if `self` was not locked by V4 PoX.
     pub fn increase_lock_v4(&mut self, new_total_locked: u128) -> Result<(), VmExecutionError> {
         let unlocked = self.unlock_available_tokens_if_any()?;
         if unlocked > 0 {

stacks-common/src/util/hash.rs

@@ -312,6 +312,11 @@ impl DoubleSha256 {
     #[inline]
     pub fn into_le(self) -> Uint256 {
         let DoubleSha256(data) = self;
+        // SAFETY: source `[u8; 32]` and target `[u64; 4]` have the same size
+        // (32 bytes) and both are POD with no invalid bit patterns. The
+        // transmute reinterprets the bytes as four u64 limbs in the host's
+        // native byte order; the subsequent `to_le()` loop normalizes each
+        // limb to little-endian so the result is host-independent.
         let mut ret: [u64; 4] = unsafe { mem::transmute(data) };
         for x in ret.iter_mut() {
             *x = x.to_le();
@@ -324,6 +329,11 @@ impl DoubleSha256 {
     pub fn into_be(self) -> Uint256 {
         let DoubleSha256(mut data) = self;
         data.reverse();
+        // SAFETY: source `[u8; 32]` and target `[u64; 4]` have the same size
+        // (32 bytes) and both are POD with no invalid bit patterns. The
+        // transmute reinterprets the (reversed) bytes as four u64 limbs in
+        // the host's native byte order; the subsequent `to_be()` loop
+        // normalizes each limb to big-endian so the result is host-independent.
         let mut ret: [u64; 4] = unsafe { mem::transmute(data) };
         for x in ret.iter_mut() {
             *x = x.to_be();

stackslib/src/chainstate/nakamoto/coordinator/mod.rs

@@ -293,7 +293,6 @@ fn find_prepare_phase_sortitions(
 ///
 /// Returns Ok(Some(reward-cycle-info)) if we found the first sortition in the prepare phase.
 /// Returns Ok(None) if we're still waiting for the PoX anchor block sortition
-/// Returns Err(Error::NotInPreparePhase) if `burn_height` is not in the prepare phase
 pub fn get_nakamoto_reward_cycle_info<U: RewardSetProvider>(
     sortition_tip: &SortitionId,
     reward_cycle: u64,