Rollup merge of rust-lang#59979 - stepancheg:num-size, r=ehuss

to_xe_bytes for isize and usize returns an array of different size

... on different platforms.

Official rustdoc of
[`usize::to_le_bytes`](https://doc.rust-lang.org/std/primitive.usize.html#method.to_le_bytes)
displays signature

```
pub fn to_ne_bytes(self) -> [u8; 8]
```

which might be misleading: this function returns 4 bytes on 32-bit
systems.

With this commit applied rustdoc for `isize` and `usize` is this:
<img width="740" alt="2019-04-15_0020" src="https://user-images.githubusercontent.com/28969/56100765-9f69b380-5f14-11e9-974c-daa25edaa881.png">

Author: Centril

src/libcore/num/mod.rs

@@ -214,11 +214,31 @@ pub mod diy_float;
 
 mod wrapping;
 
+macro_rules! usize_isize_to_xe_bytes_doc {
+    () => {"
+
+**Note**: This function returns an array of length 2, 4 or 8 bytes
+depending on the target pointer size.
+
+"}
+}
+
+
+macro_rules! usize_isize_from_xe_bytes_doc {
+    () => {"
+
+**Note**: This function takes an array of length 2, 4 or 8 bytes
+depending on the target pointer size.
+
+"}
+}
+
 // `Int` + `SignedInt` implemented for signed integers
 macro_rules! int_impl {
     ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $Min:expr, $Max:expr, $Feature:expr,
      $EndFeature:expr, $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
-     $reversed:expr, $le_bytes:expr, $be_bytes:expr) => {
+     $reversed:expr, $le_bytes:expr, $be_bytes:expr,
+     $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
         doc_comment! {
             concat!("Returns the smallest value that can be represented by this integer type.
 
@@ -2023,7 +2043,9 @@ $EndFeature, "
         doc_comment! {
             concat!("Return the memory representation of this integer as a byte array in
 big-endian (network) byte order.
-
+",
+$to_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -2041,7 +2063,9 @@ assert_eq!(bytes, ", $be_bytes, ");
 doc_comment! {
             concat!("Return the memory representation of this integer as a byte array in
 little-endian byte order.
-
+",
+$to_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -2064,7 +2088,9 @@ native byte order.
 As the target platform's native endianness is used, portable code
 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
 instead.
-
+",
+$to_xe_bytes_doc,
+"
 [`to_be_bytes`]: #method.to_be_bytes
 [`to_le_bytes`]: #method.to_le_bytes
 
@@ -2089,7 +2115,9 @@ assert_eq!(bytes, if cfg!(target_endian = \"big\") {
 doc_comment! {
             concat!("Create an integer value from its representation as a byte array in
 big endian.
-
+",
+$from_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -2120,7 +2148,9 @@ doc_comment! {
             concat!("
 Create an integer value from its representation as a byte array in
 little endian.
-
+",
+$from_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -2157,7 +2187,9 @@ appropriate instead.
 
 [`from_be_bytes`]: #method.from_be_bytes
 [`from_le_bytes`]: #method.from_le_bytes
-
+",
+$from_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -2193,28 +2225,28 @@ fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT),
 #[lang = "i8"]
 impl i8 {
     int_impl! { i8, i8, u8, 8, -128, 127, "", "", 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
-        "[0x12]", "[0x12]" }
+        "[0x12]", "[0x12]", "", "" }
 }
 
 #[lang = "i16"]
 impl i16 {
     int_impl! { i16, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
-        "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]" }
+        "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
 }
 
 #[lang = "i32"]
 impl i32 {
     int_impl! { i32, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
         "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
-        "[0x12, 0x34, 0x56, 0x78]" }
+        "[0x12, 0x34, 0x56, 0x78]", "", "" }
 }
 
 #[lang = "i64"]
 impl i64 {
     int_impl! { i64, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "", 12,
          "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
          "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
-         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
+         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", "", "" }
 }
 
 #[lang = "i128"]
@@ -2226,22 +2258,24 @@ impl i128 {
         "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
           0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
-          0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]" }
+          0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", "", "" }
 }
 
 #[cfg(target_pointer_width = "16")]
 #[lang = "isize"]
 impl isize {
     int_impl! { isize, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234",
-        "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]" }
+        "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]",
+        usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 }
 
 #[cfg(target_pointer_width = "32")]
 #[lang = "isize"]
 impl isize {
     int_impl! { isize, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
         "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
-        "[0x12, 0x34, 0x56, 0x78]" }
+        "[0x12, 0x34, 0x56, 0x78]",
+        usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 }
 
 #[cfg(target_pointer_width = "64")]
@@ -2250,14 +2284,16 @@ impl isize {
     int_impl! { isize, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "",
         12, "0xaa00000000006e1", "0x6e10aa",  "0x1234567890123456", "0x5634129078563412",
          "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
-         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
+         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
+         usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 }
 
 // `Int` + `UnsignedInt` implemented for unsigned integers
 macro_rules! uint_impl {
     ($SelfT:ty, $ActualT:ty, $BITS:expr, $MaxV:expr, $Feature:expr, $EndFeature:expr,
         $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
-        $reversed:expr, $le_bytes:expr, $be_bytes:expr) => {
+        $reversed:expr, $le_bytes:expr, $be_bytes:expr,
+        $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
         doc_comment! {
             concat!("Returns the smallest value that can be represented by this integer type.
 
@@ -3817,7 +3853,9 @@ $EndFeature, "
         doc_comment! {
             concat!("Return the memory representation of this integer as a byte array in
 big-endian (network) byte order.
-
+",
+$to_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -3835,7 +3873,9 @@ assert_eq!(bytes, ", $be_bytes, ");
         doc_comment! {
             concat!("Return the memory representation of this integer as a byte array in
 little-endian byte order.
-
+",
+$to_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -3858,7 +3898,9 @@ native byte order.
 As the target platform's native endianness is used, portable code
 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
 instead.
-
+",
+$to_xe_bytes_doc,
+"
 [`to_be_bytes`]: #method.to_be_bytes
 [`to_le_bytes`]: #method.to_le_bytes
 
@@ -3883,7 +3925,9 @@ assert_eq!(bytes, if cfg!(target_endian = \"big\") {
         doc_comment! {
             concat!("Create an integer value from its representation as a byte array in
 big endian.
-
+",
+$from_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -3914,7 +3958,9 @@ fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT),
             concat!("
 Create an integer value from its representation as a byte array in
 little endian.
-
+",
+$from_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -3951,7 +3997,9 @@ appropriate instead.
 
 [`from_be_bytes`]: #method.from_be_bytes
 [`from_le_bytes`]: #method.from_le_bytes
-
+",
+$from_xe_bytes_doc,
+"
 # Examples
 
 ```
@@ -3987,7 +4035,7 @@ fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT),
 #[lang = "u8"]
 impl u8 {
     uint_impl! { u8, u8, 8, 255, "", "", 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
-        "[0x12]" }
+        "[0x12]", "", "" }
 
 
     /// Checks if the value is within the ASCII range.
@@ -4506,21 +4554,22 @@ impl u8 {
 #[lang = "u16"]
 impl u16 {
     uint_impl! { u16, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
-        "[0x34, 0x12]", "[0x12, 0x34]" }
+        "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
 }
 
 #[lang = "u32"]
 impl u32 {
     uint_impl! { u32, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
-        "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]" }
+        "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]", "", "" }
 }
 
 #[lang = "u64"]
 impl u64 {
     uint_impl! { u64, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
         "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
         "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
-        "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
+        "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
+        "", ""}
 }
 
 #[lang = "u128"]
@@ -4531,20 +4580,23 @@ impl u128 {
         "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
           0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
-          0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]" }
+          0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
+         "", ""}
 }
 
 #[cfg(target_pointer_width = "16")]
 #[lang = "usize"]
 impl usize {
     uint_impl! { usize, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
-        "[0x34, 0x12]", "[0x12, 0x34]" }
+        "[0x34, 0x12]", "[0x12, 0x34]",
+        usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 }
 #[cfg(target_pointer_width = "32")]
 #[lang = "usize"]
 impl usize {
     uint_impl! { usize, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
-        "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]" }
+        "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
+        usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 }
 
 #[cfg(target_pointer_width = "64")]
@@ -4553,7 +4605,8 @@ impl usize {
     uint_impl! { usize, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
         "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
         "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
-         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
+         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
+        usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 }
 
 /// A classification of floating point numbers.