Rollup merge of #31535 - Ketsuban:more-detail-in-wrapping-shift-documentation, r=steveklabnik

`wrapping_shl` and `wrapping_shr` are easy to mistake for rotations, when in fact they work somewhat differently. The documentation currently available is a little sparse and easy to misinterpret, so I've added a warning to anyone who bumps into them that the equivalent rotate methods may actually be what they're looking for.

If it's deemed useful to add a symmetrical mention to the documentation for the `rotate_left` and `rotate_right` methods, I can certainly have a go at that, but my gut feeling is that people likely to want a rotate will already know about the wrapping-arithmetic methods, for example from writing CPU simulators.

src/libcore/num/mod.rs

@@ -741,6 +741,13 @@ macro_rules! int_impl {
         /// where `mask` removes any high-order bits of `rhs` that
         /// would cause the shift to exceed the bitwidth of the type.
         ///
+        /// Note that this is *not* the same as a rotate-left; the
+        /// RHS of a wrapping shift-left is restricted to the range
+        /// of the type, rather than the bits shifted out of the LHS
+        /// being returned to the other end. The primitive integer
+        /// types all implement a `rotate_left` function, which may
+        /// be what you want instead.
+        ///
         /// # Examples
         ///
         /// Basic usage:
@@ -759,6 +766,13 @@ macro_rules! int_impl {
         /// where `mask` removes any high-order bits of `rhs` that
         /// would cause the shift to exceed the bitwidth of the type.
         ///
+        /// Note that this is *not* the same as a rotate-right; the
+        /// RHS of a wrapping shift-right is restricted to the range
+        /// of the type, rather than the bits shifted out of the LHS
+        /// being returned to the other end. The primitive integer
+        /// types all implement a `rotate_right` function, which may
+        /// be what you want instead.
+        ///
         /// # Examples
         ///
         /// Basic usage: