Improve comments for assert_unchecked calls

Author: ChaiTRex

library/core/src/num/int_macros.rs

@@ -1584,31 +1584,24 @@ macro_rules! int_impl {
                     crate::num::int_sqrt::$ActualT(self as $ActualT) as $SelfT
                 };
 
-                // SAFETY: Inform the optimizer what the range of outputs is.
-                // If testing `core` crashes with no panic message and a
+                // Inform the optimizer what the range of outputs is. If
+                // testing `core` crashes with no panic message and a
                 // `num::int_sqrt::i*` test failed, it's because your edits
                 // caused these assertions to become false.
                 //
-                // Integer square root is a monotonically nondecreasing
+                // SAFETY: Integer square root is a monotonically nondecreasing
                 // function, which means that increasing the input will never
-                // cause the output to decrease.
-                //
-                // The minimum input in this `else` branch is 0. The maximum
-                // input is `<$ActualT>::MAX`.
-                //
-                // When n is 0, sqrt(n) is 0. If n increases above 0, sqrt(n)
-                // can't decrease below 0, so sqrt(n) can't decrease below 0 no
-                // matter what n is.
-                //
-                // When n is below `<$ActualT>::MAX`, sqrt(n) can't decrease at
-                // all when you increase n to `<$ActualT>::MAX`, so sqrt(n)
-                // can't be above sqrt(`<$ActualT>::MAX`) no matter what n is.
+                // cause the output to decrease. Thus, since the input for
+                // nonnegative signed integers is bounded by
+                // `[0, <$ActualT>::MAX]`, sqrt(n) will be bounded by
+                // `[sqrt(0), sqrt(<$ActualT>::MAX)]`.
                 unsafe {
-                    crate::hint::assert_unchecked(result >= 0);
                     // SAFETY: `<$ActualT>::MAX` is nonnegative.
                     const MAX_RESULT: $SelfT = unsafe {
                         crate::num::int_sqrt::$ActualT(<$ActualT>::MAX) as $SelfT
                     };
+
+                    crate::hint::assert_unchecked(result >= 0);
                     crate::hint::assert_unchecked(result <= MAX_RESULT);
                 }
 

library/core/src/num/int_sqrt.rs

@@ -171,13 +171,13 @@ macro_rules! first_stage {
 /// Generates a middle stage of the computation.
 macro_rules! middle_stage {
     ($original_bits:literal, $ty:ty, $n:ident, $s:ident, $r:ident) => {{
-        // SAFETY: Inform the optimizer that `$s` is nonzero. This will allow
-        // it to avoid generating code to handle division-by-zero panics in the
+        // Inform the optimizer that `$s` is nonzero. This will allow it to
+        // avoid generating code to handle division-by-zero panics in the
         // divisions below.
         //
-        // If the original `$n` is zero, the top of the `unsigned_fn` macro
-        // recurses instead of continuing to this point, so the original `$n`
-        // wasn't a 0 if we've reached here.
+        // SAFETY: If the original `$n` is zero, the top of the `unsigned_fn`
+        // macro recurses instead of continuing to this point, so the original
+        // `$n` wasn't a 0 if we've reached here.
         //
         // Then the `unsigned_fn` macro normalizes `$n` so that at least one of
         // the two most-significant bits is a 1.
@@ -221,11 +221,11 @@ macro_rules! middle_stage {
 /// Generates the last stage of the computation before denormalization.
 macro_rules! last_stage {
     ($ty:ty, $n:ident, $s:ident, $r:ident) => {{
-        // SAFETY: Inform the optimizer that `$s` is nonzero. This will allow
-        // it to avoid generating code to handle division-by-zero panics in the
+        // Inform the optimizer that `$s` is nonzero. This will allow it to
+        // avoid generating code to handle division-by-zero panics in the
         // division below.
         //
-        // See the proof in the `middle_stage` macro above.
+        // SAFETY: See the proof in the `middle_stage` macro above.
         unsafe { core::hint::assert_unchecked($s != 0) };
 
         const HALF_BITS: u32 = <$ty>::BITS >> 1;

library/core/src/num/nonzero.rs

@@ -1554,7 +1554,7 @@ macro_rules! nonzero_integer_signedness_dependent_methods {
             // function, which means that increasing the input will never cause
             // the output to decrease. Thus, since the input for nonzero
             // unsigned integers has a lower bound of 1, the lower bound of the
-            // result will be sqrt(1), which is 1.
+            // results will be sqrt(1), which is 1.
             unsafe {
                 hint::assert_unchecked(result >= 1);
             }

library/core/src/num/uint_macros.rs

@@ -2708,28 +2708,16 @@ macro_rules! uint_impl {
         pub const fn isqrt(self) -> Self {
             let result = crate::num::int_sqrt::$ActualT(self as $ActualT) as $SelfT;
 
-            // SAFETY: Inform the optimizer what the range of outputs is.
-            // If testing `core` crashes with no panic message and a
-            // `num::int_sqrt::u*` test failed, it's because your edits
-            // caused these assertions or the assertions in `fn isqrt` of
-            // `nonzero.rs` to become false.
+            // Inform the optimizer what the range of outputs is. If testing
+            // `core` crashes with no panic message and a `num::int_sqrt::u*`
+            // test failed, it's because your edits caused these assertions or
+            // the assertions in `fn isqrt` of `nonzero.rs` to become false.
             //
-            // Integer square root is a monotonically nondecreasing
+            // SAFETY: Integer square root is a monotonically nondecreasing
             // function, which means that increasing the input will never
-            // cause the output to decrease.
-            //
-            // The minimum input is 0. The maximum input is `<$ActualT>::MAX`.
-            //
-            // When n is 0, sqrt(n) is 0. If n increases above 0, sqrt(n)
-            // can't decrease below 0, so sqrt(n) can't decrease below 0 no
-            // matter what n is.
-            //
-            // However, the optimizer already knows that zero is the minimum
-            // value of all unsigned integer types, so we won't mention that.
-            //
-            // When n is below `<$ActualT>::MAX`, sqrt(n) can't decrease at
-            // all when you increase n to `<$ActualT>::MAX`, so sqrt(n)
-            // can't be above sqrt(`<$ActualT>::MAX`) no matter what n is.
+            // cause the output to decrease. Thus, since the input for unsigned
+            // integers is bounded by `[0, <$ActualT>::MAX]`, sqrt(n) will be
+            // bounded by `[sqrt(0), sqrt(<$ActualT>::MAX)]`.
             unsafe {
                 const MAX_RESULT: $SelfT = crate::num::int_sqrt::$ActualT(<$ActualT>::MAX) as $SelfT;
                 crate::hint::assert_unchecked(result <= MAX_RESULT);