Unrolled build for #149295

Rollup merge of #149295 - kornelski:endian_bytes, r=Mark-Simulacrum

Suggest _bytes versions of endian-converting methods

As pointed out [in this article](https://purplesyringa.moe/blog/ntoh-hton-is-a-bad-api/), the `int.to_be()`/`int.to_le()` functions are technically returning a wrong type, because endian-specific representations of integers and Rust's always-native-endian integers are different things.

I wanted to make the docs state more directly that byte swapping will result in the type having a "wrong" value, but I wasn't sure whether to delve into the special case of palindrome-like values (`0x12343412`) not changing.

I've updated the docs to suggest `{to,from}_[lb]e_bytes()` instead. These methods use `[u8; _]` for endian-specific representations, which is a different type than the native-endian `u16`/`u32`/`u64`, and this is a type-safety improvement.

Author: rust-timer

library/core/src/num/int_macros.rs

@@ -372,6 +372,8 @@ macro_rules! int_impl {
         ///
         /// On big endian this is a no-op. On little endian the bytes are swapped.
         ///
+        /// See also [from_be_bytes()](Self::from_be_bytes).
+        ///
         /// # Examples
         ///
         /// ```
@@ -402,6 +404,8 @@ macro_rules! int_impl {
         ///
         /// On little endian this is a no-op. On big endian the bytes are swapped.
         ///
+        /// See also [from_le_bytes()](Self::from_le_bytes).
+        ///
         /// # Examples
         ///
         /// ```
@@ -428,9 +432,15 @@ macro_rules! int_impl {
             }
         }
 
-        /// Converts `self` to big endian from the target's endianness.
+        /// Swaps bytes of `self` on little endian targets.
         ///
-        /// On big endian this is a no-op. On little endian the bytes are swapped.
+        /// On big endian this is a no-op.
+        ///
+        /// The returned value has the same type as `self`, and will be interpreted
+        /// as (a potentially different) value of a native-endian
+        #[doc = concat!("`", stringify!($SelfT), "`.")]
+        ///
+        /// See [`to_be_bytes()`](Self::to_be_bytes) for a type-safe alternative.
         ///
         /// # Examples
         ///
@@ -459,9 +469,15 @@ macro_rules! int_impl {
             }
         }
 
-        /// Converts `self` to little endian from the target's endianness.
+        /// Swaps bytes of `self` on big endian targets.
         ///
-        /// On little endian this is a no-op. On big endian the bytes are swapped.
+        /// On little endian this is a no-op.
+        ///
+        /// The returned value has the same type as `self`, and will be interpreted
+        /// as (a potentially different) value of a native-endian
+        #[doc = concat!("`", stringify!($SelfT), "`.")]
+        ///
+        /// See [`to_le_bytes()`](Self::to_le_bytes) for a type-safe alternative.
         ///
         /// # Examples
         ///