diff --git a/library/core/src/intrinsics/fallback.rs b/library/core/src/intrinsics/fallback.rs
index a477c2e1a70bd..d2794a5b1202d 100644
--- a/library/core/src/intrinsics/fallback.rs
+++ b/library/core/src/intrinsics/fallback.rs
@@ -151,11 +151,11 @@ impl_disjoint_bitor! {
 pub const trait FunnelShift: Copy + 'static {
     /// See [`super::unchecked_funnel_shl`]; we just need the trait indirection to handle
     /// different types since calling intrinsics with generics doesn't work.
-    unsafe fn unchecked_funnel_shl(self, rhs: Self, shift: u32) -> Self;
+    unsafe fn unchecked_funnel_shl(self, right: Self, shift: u32) -> Self;
 
     /// See [`super::unchecked_funnel_shr`]; we just need the trait indirection to handle
     /// different types since calling intrinsics with generics doesn't work.
-    unsafe fn unchecked_funnel_shr(self, rhs: Self, shift: u32) -> Self;
+    unsafe fn unchecked_funnel_shr(self, right: Self, shift: u32) -> Self;
 }
 
 macro_rules! impl_funnel_shifts {
@@ -164,7 +164,7 @@ macro_rules! impl_funnel_shifts {
         const impl FunnelShift for $type {
             #[cfg_attr(miri, track_caller)]
             #[inline]
-            unsafe fn unchecked_funnel_shl(self, rhs: Self, shift: u32) -> Self {
+            unsafe fn unchecked_funnel_shl(self, right: Self, shift: u32) -> Self {
                 // This implementation is also used by Miri so we have to check the precondition.
                 // SAFETY: this is guaranteed by the caller
                 unsafe { super::assume(shift < $type::BITS) };
@@ -181,7 +181,7 @@ macro_rules! impl_funnel_shifts {
                     unsafe {
                         super::disjoint_bitor(
                             super::unchecked_shl(self, shift),
-                            super::unchecked_shr(rhs, $type::BITS - shift),
+                            super::unchecked_shr(right, $type::BITS - shift),
                         )
                     }
                 }
@@ -189,12 +189,12 @@ macro_rules! impl_funnel_shifts {
 
             #[cfg_attr(miri, track_caller)]
             #[inline]
-            unsafe fn unchecked_funnel_shr(self, rhs: Self, shift: u32) -> Self {
+            unsafe fn unchecked_funnel_shr(self, right: Self, shift: u32) -> Self {
                 // This implementation is also used by Miri so we have to check the precondition.
                 // SAFETY: this is guaranteed by the caller
                 unsafe { super::assume(shift < $type::BITS) };
                 if shift == 0 {
-                    rhs
+                    right
                 } else {
                     // SAFETY:
                     //  - `shift < T::BITS`, which satisfies `unchecked_shr`
@@ -206,7 +206,7 @@ macro_rules! impl_funnel_shifts {
                     unsafe {
                         super::disjoint_bitor(
                             super::unchecked_shl(self, $type::BITS - shift),
-                            super::unchecked_shr(rhs, shift),
+                            super::unchecked_shr(right, shift),
                         )
                     }
                 }
diff --git a/library/core/src/num/mod.rs b/library/core/src/num/mod.rs
index 478af470637d7..aeb81bb5d6661 100644
--- a/library/core/src/num/mod.rs
+++ b/library/core/src/num/mod.rs
@@ -382,11 +382,11 @@ impl i8 {
         Min = -128,
         Max = 127,
         rot = 2,
-        rot_op = "-0x7e",
-        rot_result = "0xa",
-        swap_op = "0x12",
-        swapped = "0x12",
-        reversed = "0x48",
+        rot_op     = "-0x7e",
+        rot_result = "0x0a",
+        swap_op    = "0x12",
+        swapped    = "0x12",
+        reversed   = "0x48",
         le_bytes = "[0x12]",
         be_bytes = "[0x12]",
         to_xe_bytes_doc = i8_xe_bytes_doc!(),
@@ -407,11 +407,11 @@ impl i16 {
         Min = -32768,
         Max = 32767,
         rot = 4,
-        rot_op = "-0x5ffd",
-        rot_result = "0x3a",
-        swap_op = "0x1234",
-        swapped = "0x3412",
-        reversed = "0x2c48",
+        rot_op     = "-0x5ffd",
+        rot_result = "0x003a",
+        swap_op    = "0x1234",
+        swapped    = "0x3412",
+        reversed   = "0x2c48",
         le_bytes = "[0x34, 0x12]",
         be_bytes = "[0x12, 0x34]",
         to_xe_bytes_doc = "",
@@ -432,11 +432,11 @@ impl i32 {
         Min = -2147483648,
         Max = 2147483647,
         rot = 8,
-        rot_op = "0x10000b3",
-        rot_result = "0xb301",
-        swap_op = "0x12345678",
-        swapped = "0x78563412",
-        reversed = "0x1e6a2c48",
+        rot_op     = "0x010000b3",
+        rot_result = "0x0000b301",
+        swap_op    = "0x12345678",
+        swapped    = "0x78563412",
+        reversed   = "0x1e6a2c48",
         le_bytes = "[0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78]",
         to_xe_bytes_doc = "",
@@ -457,11 +457,11 @@ impl i64 {
         Min = -9223372036854775808,
         Max = 9223372036854775807,
         rot = 12,
-        rot_op = "0xaa00000000006e1",
-        rot_result = "0x6e10aa",
-        swap_op = "0x1234567890123456",
-        swapped = "0x5634129078563412",
-        reversed = "0x6a2c48091e6a2c48",
+        rot_op     = "0x0aa00000000006e1",
+        rot_result = "0x00000000006e10aa",
+        swap_op    = "0x1234567890123456",
+        swapped    = "0x5634129078563412",
+        reversed   = "0x6a2c48091e6a2c48",
         le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
         to_xe_bytes_doc = "",
@@ -482,11 +482,11 @@ impl i128 {
         Min = -170141183460469231731687303715884105728,
         Max = 170141183460469231731687303715884105727,
         rot = 16,
-        rot_op = "0x13f40000000000000000000000004f76",
-        rot_result = "0x4f7613f4",
-        swap_op = "0x12345678901234567890123456789012",
-        swapped = "0x12907856341290785634129078563412",
-        reversed = "0x48091e6a2c48091e6a2c48091e6a2c48",
+        rot_op     = "0x13f40000000000000000000000004f76",
+        rot_result = "0x0000000000000000000000004f7613f4",
+        swap_op    = "0x12345678901234567890123456789012",
+        swapped    = "0x12907856341290785634129078563412",
+        reversed   = "0x48091e6a2c48091e6a2c48091e6a2c48",
         le_bytes = "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
             0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
@@ -510,11 +510,11 @@ impl isize {
         Min = -32768,
         Max = 32767,
         rot = 4,
-        rot_op = "-0x5ffd",
-        rot_result = "0x3a",
-        swap_op = "0x1234",
-        swapped = "0x3412",
-        reversed = "0x2c48",
+        rot_op     = "-0x5ffd",
+        rot_result = "0x003a",
+        swap_op    = "0x1234",
+        swapped    = "0x3412",
+        reversed   = "0x2c48",
         le_bytes = "[0x34, 0x12]",
         be_bytes = "[0x12, 0x34]",
         to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
@@ -536,11 +536,11 @@ impl isize {
         Min = -2147483648,
         Max = 2147483647,
         rot = 8,
-        rot_op = "0x10000b3",
-        rot_result = "0xb301",
-        swap_op = "0x12345678",
-        swapped = "0x78563412",
-        reversed = "0x1e6a2c48",
+        rot_op     = "0x010000b3",
+        rot_result = "0x0000b301",
+        swap_op    = "0x12345678",
+        swapped    = "0x78563412",
+        reversed   = "0x1e6a2c48",
         le_bytes = "[0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78]",
         to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
@@ -562,11 +562,11 @@ impl isize {
         Min = -9223372036854775808,
         Max = 9223372036854775807,
         rot = 12,
-        rot_op = "0xaa00000000006e1",
-        rot_result = "0x6e10aa",
-        swap_op = "0x1234567890123456",
-        swapped = "0x5634129078563412",
-        reversed = "0x6a2c48091e6a2c48",
+        rot_op     = "0x0aa00000000006e1",
+        rot_result = "0x00000000006e10aa",
+        swap_op    = "0x1234567890123456",
+        swapped    = "0x5634129078563412",
+        reversed   = "0x6a2c48091e6a2c48",
         le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
         to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
@@ -588,17 +588,17 @@ impl u8 {
         BITS_MINUS_ONE = 7,
         MAX = 255,
         rot = 2,
-        rot_op = "0x82",
-        rot_result = "0xa",
-        fsh_op = "0x36",
-        fshl_result = "0x8",
-        fshr_result = "0x8d",
-        clmul_lhs = "0x12",
-        clmul_rhs = "0x34",
+        rot_op       = "0x82",
+        rot_result   = "0x0a",
+        fsh_op       = "0x36",
+        fshl_result  = "0x08",
+        fshr_result  = "0x8d",
+        clmul_lhs    = "0x12",
+        clmul_rhs    = "0x34",
         clmul_result = "0x28",
-        swap_op = "0x12",
-        swapped = "0x12",
-        reversed = "0x48",
+        swap_op      = "0x12",
+        swapped      = "0x12",
+        reversed     = "0x48",
         le_bytes = "[0x12]",
         be_bytes = "[0x12]",
         to_xe_bytes_doc = u8_xe_bytes_doc!(),
@@ -1236,17 +1236,17 @@ impl u16 {
         BITS_MINUS_ONE = 15,
         MAX = 65535,
         rot = 4,
-        rot_op = "0xa003",
-        rot_result = "0x3a",
-        fsh_op = "0x2de",
-        fshl_result = "0x30",
-        fshr_result = "0x302d",
-        clmul_lhs = "0x9012",
-        clmul_rhs = "0xcd34",
-        clmul_result = "0x928",
-        swap_op = "0x1234",
-        swapped = "0x3412",
-        reversed = "0x2c48",
+        rot_op       = "0xa003",
+        rot_result   = "0x003a",
+        fsh_op       = "0x02de",
+        fshl_result  = "0x0030",
+        fshr_result  = "0x302d",
+        clmul_lhs    = "0x9012",
+        clmul_rhs    = "0xcd34",
+        clmul_result = "0x0928",
+        swap_op      = "0x1234",
+        swapped      = "0x3412",
+        reversed     = "0x2c48",
         le_bytes = "[0x34, 0x12]",
         be_bytes = "[0x12, 0x34]",
         to_xe_bytes_doc = "",
@@ -1292,17 +1292,17 @@ impl u32 {
         BITS_MINUS_ONE = 31,
         MAX = 4294967295,
         rot = 8,
-        rot_op = "0x10000b3",
-        rot_result = "0xb301",
-        fsh_op = "0x2fe78e45",
-        fshl_result = "0xb32f",
-        fshr_result = "0xb32fe78e",
-        clmul_lhs = "0x56789012",
-        clmul_rhs = "0xf52ecd34",
+        rot_op       = "0x010000b3",
+        rot_result   = "0x0000b301",
+        fsh_op       = "0x2fe78e45",
+        fshl_result  = "0x0000b32f",
+        fshr_result  = "0xb32fe78e",
+        clmul_lhs    = "0x56789012",
+        clmul_rhs    = "0xf52ecd34",
         clmul_result = "0x9b980928",
-        swap_op = "0x12345678",
-        swapped = "0x78563412",
-        reversed = "0x1e6a2c48",
+        swap_op      = "0x12345678",
+        swapped      = "0x78563412",
+        reversed     = "0x1e6a2c48",
         le_bytes = "[0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78]",
         to_xe_bytes_doc = "",
@@ -1324,17 +1324,17 @@ impl u64 {
         BITS_MINUS_ONE = 63,
         MAX = 18446744073709551615,
         rot = 12,
-        rot_op = "0xaa00000000006e1",
-        rot_result = "0x6e10aa",
-        fsh_op = "0x2fe78e45983acd98",
-        fshl_result = "0x6e12fe",
-        fshr_result = "0x6e12fe78e45983ac",
-        clmul_lhs = "0x7890123456789012",
-        clmul_rhs = "0xdd358416f52ecd34",
-        clmul_result = "0xa6299579b980928",
-        swap_op = "0x1234567890123456",
-        swapped = "0x5634129078563412",
-        reversed = "0x6a2c48091e6a2c48",
+        rot_op       = "0x0aa00000000006e1",
+        rot_result   = "0x00000000006e10aa",
+        fsh_op       = "0x2fe78e45983acd98",
+        fshl_result  = "0x00000000006e12fe",
+        fshr_result  = "0x6e12fe78e45983ac",
+        clmul_lhs    = "0x7890123456789012",
+        clmul_rhs    = "0xdd358416f52ecd34",
+        clmul_result = "0x0a6299579b980928",
+        swap_op      = "0x1234567890123456",
+        swapped      = "0x5634129078563412",
+        reversed     = "0x6a2c48091e6a2c48",
         le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
         to_xe_bytes_doc = "",
@@ -1356,17 +1356,17 @@ impl u128 {
         BITS_MINUS_ONE = 127,
         MAX = 340282366920938463463374607431768211455,
         rot = 16,
-        rot_op = "0x13f40000000000000000000000004f76",
-        rot_result = "0x4f7613f4",
-        fsh_op = "0x2fe78e45983acd98039000008736273",
-        fshl_result = "0x4f7602fe",
-        fshr_result = "0x4f7602fe78e45983acd9803900000873",
-        clmul_lhs = "0x12345678901234567890123456789012",
-        clmul_rhs = "0x4317e40ab4ddcf05dd358416f52ecd34",
+        rot_op       = "0x13f40000000000000000000000004f76",
+        rot_result   = "0x0000000000000000000000004f7613f4",
+        fsh_op       = "0x02fe78e45983acd98039000008736273",
+        fshl_result  = "0x0000000000000000000000004f7602fe",
+        fshr_result  = "0x4f7602fe78e45983acd9803900000873",
+        clmul_lhs    = "0x12345678901234567890123456789012",
+        clmul_rhs    = "0x4317e40ab4ddcf05dd358416f52ecd34",
         clmul_result = "0xb9cf660de35d0c170a6299579b980928",
-        swap_op = "0x12345678901234567890123456789012",
-        swapped = "0x12907856341290785634129078563412",
-        reversed = "0x48091e6a2c48091e6a2c48091e6a2c48",
+        swap_op      = "0x12345678901234567890123456789012",
+        swapped      = "0x12907856341290785634129078563412",
+        reversed     = "0x48091e6a2c48091e6a2c48091e6a2c48",
         le_bytes = "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
             0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
@@ -1390,17 +1390,17 @@ impl usize {
         BITS_MINUS_ONE = 15,
         MAX = 65535,
         rot = 4,
-        rot_op = "0xa003",
-        rot_result = "0x3a",
-        fsh_op = "0x2de",
-        fshl_result = "0x30",
-        fshr_result = "0x302d",
-        clmul_lhs = "0x9012",
-        clmul_rhs = "0xcd34",
-        clmul_result = "0x928",
-        swap_op = "0x1234",
-        swapped = "0x3412",
-        reversed = "0x2c48",
+        rot_op       = "0xa003",
+        rot_result   = "0x003a",
+        fsh_op       = "0x02de",
+        fshl_result  = "0x0030",
+        fshr_result  = "0x302d",
+        clmul_lhs    = "0x9012",
+        clmul_rhs    = "0xcd34",
+        clmul_result = "0x0928",
+        swap_op      = "0x1234",
+        swapped      = "0x3412",
+        reversed     = "0x2c48",
         le_bytes = "[0x34, 0x12]",
         be_bytes = "[0x12, 0x34]",
         to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
@@ -1422,17 +1422,17 @@ impl usize {
         BITS_MINUS_ONE = 31,
         MAX = 4294967295,
         rot = 8,
-        rot_op = "0x10000b3",
-        rot_result = "0xb301",
-        fsh_op = "0x2fe78e45",
-        fshl_result = "0xb32f",
-        fshr_result = "0xb32fe78e",
-        clmul_lhs = "0x56789012",
-        clmul_rhs = "0xf52ecd34",
+        rot_op       = "0x010000b3",
+        rot_result   = "0x0000b301",
+        fsh_op       = "0x2fe78e45",
+        fshl_result  = "0x0000b32f",
+        fshr_result  = "0xb32fe78e",
+        clmul_lhs    = "0x56789012",
+        clmul_rhs    = "0xf52ecd34",
         clmul_result = "0x9b980928",
-        swap_op = "0x12345678",
-        swapped = "0x78563412",
-        reversed = "0x1e6a2c48",
+        swap_op      = "0x12345678",
+        swapped      = "0x78563412",
+        reversed     = "0x1e6a2c48",
         le_bytes = "[0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78]",
         to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
@@ -1454,17 +1454,17 @@ impl usize {
         BITS_MINUS_ONE = 63,
         MAX = 18446744073709551615,
         rot = 12,
-        rot_op = "0xaa00000000006e1",
-        rot_result = "0x6e10aa",
-        fsh_op = "0x2fe78e45983acd98",
-        fshl_result = "0x6e12fe",
-        fshr_result = "0x6e12fe78e45983ac",
-        clmul_lhs = "0x7890123456789012",
-        clmul_rhs = "0xdd358416f52ecd34",
+        rot_op       = "0x0aa00000000006e1",
+        rot_result   = "0x00000000006e10aa",
+        fsh_op       = "0x2fe78e45983acd98",
+        fshl_result  = "0x00000000006e12fe",
+        fshr_result  = "0x6e12fe78e45983ac",
+        clmul_lhs    = "0x7890123456789012",
+        clmul_rhs    = "0xdd358416f52ecd34",
         clmul_result = "0xa6299579b980928",
-        swap_op = "0x1234567890123456",
-        swapped = "0x5634129078563412",
-        reversed = "0x6a2c48091e6a2c48",
+        swap_op      = "0x1234567890123456",
+        swapped      = "0x5634129078563412",
+        reversed     = "0x6a2c48091e6a2c48",
         le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
         to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs
index 2e69c67c3597a..5d5df10694197 100644
--- a/library/core/src/num/uint_macros.rs
+++ b/library/core/src/num/uint_macros.rs
@@ -504,74 +504,116 @@ macro_rules! uint_impl {
             return intrinsics::rotate_right(self, n);
         }
 
-        /// Performs a left funnel shift (concatenates `self` with `rhs`, with `self`
-        /// making up the most significant half, then shifts the combined value left
-        /// by `n`, and most significant half is extracted to produce the result).
+        /// Performs a left funnel shift.
         ///
-        /// Please note this isn't the same operation as the `<<` shifting operator or
-        /// [`rotate_left`](Self::rotate_left), although `a.funnel_shl(a, n)` is *equivalent*
-        /// to `a.rotate_left(n)`.
+        /// This operation can be thought of as concatenating `self` and `right` into an
+        /// integer twice the size of
+        #[doc = concat!("`", stringify!($SelfT) , "`,")]
+        /// performing a left shift by `n`, and returning the **left half** of the result.
+        ///
+        /// The name comes from "funneling" a wider integer to a narrower integer.
         ///
         /// # Panics
         ///
-        /// If `n` is greater than or equal to the number of bits in `self`
+        /// This function will panic if `n` is greater than or equal to the number of
+        /// bits in `self`.
         ///
         /// # Examples
         ///
-        /// Basic usage:
+        /// ```
+        /// #![feature(funnel_shifts)]
+        ///
+        #[doc = concat!("let a = ", $rot_op, "_", stringify!($SelfT), ";")]
+        #[doc = concat!("let b = ", $fsh_op, "_", stringify!($SelfT), ";")]
+        ///
+        #[doc = concat!("assert_eq!(a.funnel_shl(b, ", $rot, "), ", $fshl_result, ");")]
+        ///
+        /// // Using zeros as the right operand acts as a normal shift left
+        #[doc = concat!("assert_eq!(a.funnel_shl(0, ", $rot, "), a << ", $rot, ");")]
+        ///
+        /// // Shifting by 0 returns `self` unchanged
+        #[doc = concat!("assert_eq!(a.funnel_shl(b, 0), a);")]
         ///
+        /// // Using the same value as the right operand acts as a rotate
+        #[doc = concat!("assert_eq!(a.funnel_shl(a, ", $rot, "), a.rotate_left(", $rot, "));")]
         /// ```
+        ///
+        /// Note that while `funnel_shl` can act as a rotate, it does not allow for
+        /// rotating by an unbounded amount like [`rotate_left`](Self::rotate_left) does:
+        ///
+        /// ```should_panic
         /// #![feature(funnel_shifts)]
-        #[doc = concat!("let a = ", $rot_op, stringify!($SelfT), ";")]
-        #[doc = concat!("let b = ", $fsh_op, stringify!($SelfT), ";")]
-        #[doc = concat!("let m = ", $fshl_result, ";")]
         ///
-        #[doc = concat!("assert_eq!(a.funnel_shl(b, ", $rot, "), m);")]
+        #[doc = concat!("let a = ", stringify!($SelfT), "::MAX;")]
+        /// // Okay
+        #[doc = concat!("let _ = a.rotate_left(", stringify!($SelfT), "::BITS);")]
+        /// // Panics
+        #[doc = concat!("let _ = a.funnel_shl(a, ", stringify!($SelfT), "::BITS);")]
         /// ```
         #[rustc_const_unstable(feature = "funnel_shifts", issue = "145686")]
         #[unstable(feature = "funnel_shifts", issue = "145686")]
-        #[must_use = "this returns the result of the operation, \
-                      without modifying the original"]
+        #[must_use = "this returns the result of the operation, without modifying the original"]
         #[inline(always)]
-        pub const fn funnel_shl(self, rhs: Self, n: u32) -> Self {
+        pub const fn funnel_shl(self, right: Self, n: u32) -> Self {
             assert!(n < Self::BITS, "attempt to funnel shift left with overflow");
             // SAFETY: just checked that `shift` is in-range
-            unsafe { self.unchecked_funnel_shl(rhs, n) }
+            unsafe { self.unchecked_funnel_shl(right, n) }
         }
 
-        /// Performs a right funnel shift (concatenates `self` and `rhs`, with `self`
-        /// making up the most significant half, then shifts the combined value right
-        /// by `n`, and least significant half is extracted to produce the result).
+        /// Performs a right funnel shift.
+        ///
+        /// This operation can be thought of as concatenating `self` and `right` into an
+        /// integer twice the size of
+        #[doc = concat!("`", stringify!($SelfT) , "`,")]
+        /// performing a right shift by `n`, and returning the **left half** of the result.
         ///
-        /// Please note this isn't the same operation as the `>>` shifting operator or
-        /// [`rotate_right`](Self::rotate_right), although `a.funnel_shr(a, n)` is *equivalent*
-        /// to `a.rotate_right(n)`.
+        /// The name comes from "funneling" a wider integer to a narrower integer.
         ///
         /// # Panics
         ///
-        /// If `n` is greater than or equal to the number of bits in `self`
+        /// This function will panic if `n` is greater than or equal to the number of
+        /// bits in `self`.
         ///
         /// # Examples
         ///
-        /// Basic usage:
+        /// ```
+        /// #![feature(funnel_shifts)]
+        ///
+        #[doc = concat!("let a = ", $rot_op, "_", stringify!($SelfT), ";")]
+        #[doc = concat!("let b = ", $fsh_op, "_", stringify!($SelfT), ";")]
+        ///
+        #[doc = concat!("assert_eq!(a.funnel_shr(b, ", $rot, "), ", $fshr_result, ");")]
+        ///
+        /// // Using zeros as the left operand acts as a normal shift right
+        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".funnel_shr(a, ", $rot, "), a >> ", $rot, ");")]
         ///
+        /// // Shifting by 0 returns `right` unchanged
+        #[doc = concat!("assert_eq!(b.funnel_shr(a, 0), a);")]
+        ///
+        /// // Using the same value as the right operand acts as a rotate
+        #[doc = concat!("assert_eq!(a.funnel_shr(a, ", $rot, "), a.rotate_right(", $rot, "));")]
         /// ```
+        ///
+        /// Note that while `funnel_shr` can act as a rotate, it does not allow for
+        /// rotating by an unbounded amount like [`rotate_right`](Self::rotate_right) does:
+        ///
+        /// ```should_panic
         /// #![feature(funnel_shifts)]
-        #[doc = concat!("let a = ", $rot_op, stringify!($SelfT), ";")]
-        #[doc = concat!("let b = ", $fsh_op, stringify!($SelfT), ";")]
-        #[doc = concat!("let m = ", $fshr_result, ";")]
         ///
-        #[doc = concat!("assert_eq!(a.funnel_shr(b, ", $rot, "), m);")]
+        #[doc = concat!("let a = ", stringify!($SelfT), "::MAX;")]
+        /// // Okay
+        #[doc = concat!("let _ = a.rotate_right(", stringify!($SelfT), "::BITS);")]
+        /// // Panics
+        #[doc = concat!("let _ = a.funnel_shr(a, ", stringify!($SelfT), "::BITS);")]
         /// ```
         #[rustc_const_unstable(feature = "funnel_shifts", issue = "145686")]
         #[unstable(feature = "funnel_shifts", issue = "145686")]
-        #[must_use = "this returns the result of the operation, \
-                      without modifying the original"]
+        #[must_use = "this returns the result of the operation, without modifying the original"]
         #[inline(always)]
-        pub const fn funnel_shr(self, rhs: Self, n: u32) -> Self {
+        pub const fn funnel_shr(self, right: Self, n: u32) -> Self {
             assert!(n < Self::BITS, "attempt to funnel shift right with overflow");
             // SAFETY: just checked that `shift` is in-range
-            unsafe { self.unchecked_funnel_shr(rhs, n) }
+            unsafe { self.unchecked_funnel_shr(right, n) }
         }
 
         /// Unchecked funnel shift left.
@@ -584,11 +626,10 @@ macro_rules! uint_impl {
         ///
         #[rustc_const_unstable(feature = "funnel_shifts", issue = "145686")]
         #[unstable(feature = "funnel_shifts", issue = "145686")]
-        #[must_use = "this returns the result of the operation, \
-                      without modifying the original"]
+        #[must_use = "this returns the result of the operation, without modifying the original"]
         #[inline(always)]
         #[track_caller]
-        pub const unsafe fn unchecked_funnel_shl(self, low: Self, n: u32) -> Self {
+        pub const unsafe fn unchecked_funnel_shl(self, right: Self, n: u32) -> Self {
             assert_unsafe_precondition!(
                 check_language_ub,
                 concat!(stringify!($SelfT), "::unchecked_funnel_shl cannot overflow"),
@@ -597,7 +638,7 @@ macro_rules! uint_impl {
 
             // SAFETY: this is guaranteed to be safe by the caller.
             unsafe {
-                intrinsics::unchecked_funnel_shl(self, low, n)
+                intrinsics::unchecked_funnel_shl(self, right, n)
             }
         }
 
@@ -611,11 +652,10 @@ macro_rules! uint_impl {
         ///
         #[rustc_const_unstable(feature = "funnel_shifts", issue = "145686")]
         #[unstable(feature = "funnel_shifts", issue = "145686")]
-        #[must_use = "this returns the result of the operation, \
-                      without modifying the original"]
+        #[must_use = "this returns the result of the operation, without modifying the original"]
         #[inline(always)]
         #[track_caller]
-        pub const unsafe fn unchecked_funnel_shr(self, low: Self, n: u32) -> Self {
+        pub const unsafe fn unchecked_funnel_shr(self, right: Self, n: u32) -> Self {
             assert_unsafe_precondition!(
                 check_language_ub,
                 concat!(stringify!($SelfT), "::unchecked_funnel_shr cannot overflow"),
@@ -624,7 +664,7 @@ macro_rules! uint_impl {
 
             // SAFETY: this is guaranteed to be safe by the caller.
             unsafe {
-                intrinsics::unchecked_funnel_shr(self, low, n)
+                intrinsics::unchecked_funnel_shr(self, right, n)
             }
         }