Auto merge of #50465 - clarcharr:wrapping, r=KodrAus

Add missing Wrapping methods, use doc_comment!

Re-opened version of #49393 . Finishing touches for #32463.

Note that this adds `Shl` and `Shr` implementations for `Wrapping<i128>` and `Wrapping<u128>`, which were previously missed. This is technically insta-stable, but I don't know why this would be a problem.

src/libcore/num/mod.rs

@@ -168,8 +168,6 @@ impl<T: fmt::UpperHex> fmt::UpperHex for Wrapping<T> {
     }
 }
 
-mod wrapping;
-
 // All these modules are technically private and only exposed for coretests:
 pub mod flt2dec;
 pub mod dec2flt;
@@ -183,6 +181,8 @@ macro_rules! doc_comment {
     };
 }
 
+mod wrapping;
+
 // `Int` + `SignedInt` implemented for signed integers
 macro_rules! int_impl {
     ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $Min:expr, $Max:expr, $Feature:expr,
@@ -3401,6 +3401,30 @@ $EndFeature, "
             }
         }
 
+        doc_comment! {
+            concat!("Returns the smallest power of two greater than or equal to `n`. If
+the next power of two is greater than the type's maximum value,
+the return value is wrapped to `0`.
+
+# Examples
+
+Basic usage:
+
+```
+#![feature(wrapping_next_power_of_two)]
+", $Feature, "
+assert_eq!(2", stringify!($SelfT), ".wrapping_next_power_of_two(), 2);
+assert_eq!(3", stringify!($SelfT), ".wrapping_next_power_of_two(), 4);
+assert_eq!(", stringify!($SelfT), "::max_value().wrapping_next_power_of_two(), 0);",
+$EndFeature, "
+```"),
+            #[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
+                       reason = "needs decision on wrapping behaviour")]
+            pub fn wrapping_next_power_of_two(self) -> Self {
+                self.one_less_than_next_power_of_two().wrapping_add(1)
+            }
+        }
+
         /// Return the memory representation of this integer as a byte array.
         ///
         /// The target platform’s native endianness is used.