Add doctests to existing `f16` and `f128` functions

The symbols that these tests rely on are not available on all platforms
and some ABIs are buggy, tests that rely on external functions are
configured to only run on x86 (`f128`) or aarch64 (`f16`).

2 files changed, 68 insertions, 4 deletions

diff --git a/library/core/src/num/f128.rs b/library/core/src/num/f128.rs
index 129f62fb43d..490d7bd504d 100644
--- a/library/core/src/num/f128.rs
+++ b/library/core/src/num/f128.rs
@@ -221,8 +221,22 @@ impl f128 {
     pub const MAX_10_EXP: i32 = 4_932;
 
     /// Returns `true` if this value is NaN.
+    ///
+    /// ```
+    /// #![feature(f128)]
+    /// # // FIXME(f16_f128): remove when `unordtf2` is available
+    /// # #[cfg(target_arch = "x86_64", target_os = "linux")] {
+    ///
+    /// let nan = f128::NAN;
+    /// let f = 7.0_f128;
+    ///
+    /// assert!(nan.is_nan());
+    /// assert!(!f.is_nan());
+    /// # }
+    /// ```
     #[inline]
     #[must_use]
+    #[cfg(not(bootstrap))]
     #[unstable(feature = "f128", issue = "116909")]
     #[allow(clippy::eq_op)] // > if you intended to check if the operand is NaN, use `.is_nan()` instead :)
     pub const fn is_nan(self) -> bool {
@@ -234,7 +248,7 @@ impl f128 {
     /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
     /// the bit pattern of NaNs are conserved over arithmetic operations, the result of
     /// `is_sign_positive` on a NaN might produce an unexpected result in some cases.
-    /// See [explanation of NaN as a special value](f32) for more info.
+    /// See [explanation of NaN as a special value](f128) for more info.
     ///
     /// ```
     /// #![feature(f128)]
@@ -257,7 +271,7 @@ impl f128 {
     /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
     /// the bit pattern of NaNs are conserved over arithmetic operations, the result of
     /// `is_sign_negative` on a NaN might produce an unexpected result in some cases.
-    /// See [explanation of NaN as a special value](f32) for more info.
+    /// See [explanation of NaN as a special value](f128) for more info.
     ///
     /// ```
     /// #![feature(f128)]
@@ -287,6 +301,14 @@ impl f128 {
     ///
     /// Note that this function is distinct from `as` casting, which attempts to
     /// preserve the *numeric* value, and not the bitwise value.
+    ///
+    /// ```
+    /// #![feature(f128)]
+    ///
+    /// # // FIXME(f16_f128): enable this once const casting works
+    /// # // assert_ne!((1f128).to_bits(), 1f128 as u128); // to_bits() is not casting!
+    /// assert_eq!((12.5f128).to_bits(), 0x40029000000000000000000000000000);
+    /// ```
     #[inline]
     #[unstable(feature = "f128", issue = "116909")]
     #[must_use = "this returns the result of the operation, without modifying the original"]
@@ -326,6 +348,16 @@ impl f128 {
     ///
     /// Note that this function is distinct from `as` casting, which attempts to
     /// preserve the *numeric* value, and not the bitwise value.
+    ///
+    /// ```
+    /// #![feature(f128)]
+    /// #  // FIXME(f16_f128): remove when `eqtf2` is available
+    /// # #[cfg(all(target_arch = "x86_64", target_os = "linux"))] {
+    ///
+    /// let v = f128::from_bits(0x40029000000000000000000000000000);
+    /// assert_eq!(v, 12.5);
+    /// # }
+    /// ```
     #[inline]
     #[must_use]
     #[unstable(feature = "f128", issue = "116909")]
diff --git a/library/core/src/num/f16.rs b/library/core/src/num/f16.rs
index 7a488cd6bf6..4b0c25fcce9 100644
--- a/library/core/src/num/f16.rs
+++ b/library/core/src/num/f16.rs
@@ -216,8 +216,21 @@ impl f16 {
     pub const MAX_10_EXP: i32 = 4;
 
     /// Returns `true` if this value is NaN.
+    ///
+    /// ```
+    /// #![feature(f16)]
+    /// # #[cfg(target_arch = "x86_64")] { // FIXME(f16_f128): remove when ABI bugs are fixed
+    ///
+    /// let nan = f16::NAN;
+    /// let f = 7.0_f16;
+    ///
+    /// assert!(nan.is_nan());
+    /// assert!(!f.is_nan());
+    /// # }
+    /// ```
     #[inline]
     #[must_use]
+    #[cfg(not(bootstrap))]
     #[unstable(feature = "f16", issue = "116909")]
     #[allow(clippy::eq_op)] // > if you intended to check if the operand is NaN, use `.is_nan()` instead :)
     pub const fn is_nan(self) -> bool {
@@ -229,7 +242,7 @@ impl f16 {
     /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
     /// the bit pattern of NaNs are conserved over arithmetic operations, the result of
     /// `is_sign_positive` on a NaN might produce an unexpected result in some cases.
-    /// See [explanation of NaN as a special value](f32) for more info.
+    /// See [explanation of NaN as a special value](f16) for more info.
     ///
     /// ```
     /// #![feature(f16)]
@@ -252,7 +265,7 @@ impl f16 {
     /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
     /// the bit pattern of NaNs are conserved over arithmetic operations, the result of
     /// `is_sign_negative` on a NaN might produce an unexpected result in some cases.
-    /// See [explanation of NaN as a special value](f32) for more info.
+    /// See [explanation of NaN as a special value](f16) for more info.
     ///
     /// ```
     /// #![feature(f16)]
@@ -282,6 +295,16 @@ impl f16 {
     ///
     /// Note that this function is distinct from `as` casting, which attempts to
     /// preserve the *numeric* value, and not the bitwise value.
+    ///
+    /// ```
+    /// #![feature(f16)]
+    /// # #[cfg(target_arch = "aarch64")] { // FIXME(f16_F128): rust-lang/rust#123885
+    ///
+    /// # // FIXME(f16_f128): enable this once const casting works
+    /// # // assert_ne!((1f16).to_bits(), 1f16 as u128); // to_bits() is not casting!
+    /// assert_eq!((12.5f16).to_bits(), 0x4a40);
+    /// # }
+    /// ```
     #[inline]
     #[unstable(feature = "f16", issue = "116909")]
     #[must_use = "this returns the result of the operation, without modifying the original"]
@@ -321,6 +344,15 @@ impl f16 {
     ///
     /// Note that this function is distinct from `as` casting, which attempts to
     /// preserve the *numeric* value, and not the bitwise value.
+    ///
+    /// ```
+    /// #![feature(f16)]
+    /// # #[cfg(target_arch = "aarch64")] { // FIXME(f16_F128): rust-lang/rust#123885
+    ///
+    /// let v = f16::from_bits(0x4a40);
+    /// assert_eq!(v, 12.5);
+    /// # }
+    /// ```
     #[inline]
     #[must_use]
     #[unstable(feature = "f16", issue = "116909")]