doc: expand description for f32 and f64 associated constants

This explains the meaning of some of the floating-point associated constants.

Author: tspiteri

library/core/src/num/f32.rs

@@ -357,38 +357,76 @@ impl f32 {
 pubconstMANTISSA_DIGITS:u32 = 24;
 
 /// Approximate number of significant digits in base 10.
+///
+/// This is the maximum <i>x</i> such that any decimal number with <i>x</i>
+/// significant digits can be converted to `f32` and back without loss.
+///
+/// Equal to floor(log<sub>10</sub>&nbsp;2<sup>[`MANTISSA_DIGITS`]&nbsp;&minus;&nbsp;1</sup>).
+///
+/// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstDIGITS:u32 = 6;
 
 /// [Machine epsilon] value for `f32`.
 ///
 /// This is the difference between `1.0` and the next larger representable number.
 ///
+/// Equal to 2<sup>1&nbsp;&minus;&nbsp;[`MANTISSA_DIGITS`]</sup>.
+///
 /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon
+/// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstEPSILON:f32 = 1.19209290e-07_f32;
 
 /// Smallest finite `f32` value.
+///
+/// Equal to &minus;[`MAX`].
+///
+/// [`MAX`]: f32::MAX
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN:f32 = -3.40282347e+38_f32;
 /// Smallest positive normal `f32` value.
+///
+/// Equal to 2<sup>[`MIN_EXP`]&nbsp;&minus;&nbsp;1</sup>.
+///
+/// [`MIN_EXP`]: f32::MIN_EXP
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN_POSITIVE:f32 = 1.17549435e-38_f32;
 /// Largest finite `f32` value.
+///
+/// Equal to
+/// (1&nbsp;&minus;&nbsp;2<sup>&minus;[`MANTISSA_DIGITS`]</sup>)&nbsp;2<sup>[`MAX_EXP`]</sup>.
+///
+/// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS
+/// [`MAX_EXP`]: f32::MAX_EXP
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMAX:f32 = 3.40282347e+38_f32;
 
 /// One greater than the minimum possible normal power of 2 exponent.
+///
+/// If <i>x</i>&nbsp;=&nbsp;`MIN_EXP`, then normal numbers
+/// ≥&nbsp;0.5&nbsp;×&nbsp;2<sup><i>x</i></sup>.
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN_EXP:i32 = -125;
 /// Maximum possible power of 2 exponent.
+///
+/// If <i>x</i>&nbsp;=&nbsp;`MAX_EXP`, then normal numbers
+/// &lt;&nbsp;1&nbsp;×&nbsp;2<sup><i>x</i></sup>.
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMAX_EXP:i32 = 128;
 
-/// Minimum possible normal power of 10 exponent.
+/// Minimum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
+///
+/// Equal to ceil(log<sub>10</sub>&nbsp;[`MIN_POSITIVE`]).
+///
+/// [`MIN_POSITIVE`]: f32::MIN_POSITIVE
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN_10_EXP:i32 = -37;
-/// Maximum possible power of 10 exponent.
+/// Maximum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
+///
+/// Equal to floor(log<sub>10</sub>&nbsp;[`MAX`]).
+///
+/// [`MAX`]: f32::MAX
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMAX_10_EXP:i32 = 38;
 

library/core/src/num/f64.rs

@@ -356,38 +356,76 @@ impl f64 {
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMANTISSA_DIGITS:u32 = 53;
 /// Approximate number of significant digits in base 10.
+///
+/// This is the maximum <i>x</i> such that any decimal number with <i>x</i>
+/// significant digits can be converted to `f64` and back without loss.
+///
+/// Equal to floor(log<sub>10</sub>&nbsp;2<sup>[`MANTISSA_DIGITS`]&nbsp;&minus;&nbsp;1</sup>).
+///
+/// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstDIGITS:u32 = 15;
 
 /// [Machine epsilon] value for `f64`.
 ///
 /// This is the difference between `1.0` and the next larger representable number.
 ///
+/// Equal to 2<sup>1&nbsp;&minus;&nbsp;[`MANTISSA_DIGITS`]</sup>.
+///
 /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon
+/// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstEPSILON:f64 = 2.2204460492503131e-16_f64;
 
 /// Smallest finite `f64` value.
+///
+/// Equal to &minus;[`MAX`].
+///
+/// [`MAX`]: f64::MAX
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN:f64 = -1.7976931348623157e+308_f64;
 /// Smallest positive normal `f64` value.
+///
+/// Equal to 2<sup>[`MIN_EXP`]&nbsp;&minus;&nbsp;1</sup>.
+///
+/// [`MIN_EXP`]: f64::MIN_EXP
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN_POSITIVE:f64 = 2.2250738585072014e-308_f64;
 /// Largest finite `f64` value.
+///
+/// Equal to
+/// (1&nbsp;&minus;&nbsp;2<sup>&minus;[`MANTISSA_DIGITS`]</sup>)&nbsp;2<sup>[`MAX_EXP`]</sup>.
+///
+/// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS
+/// [`MAX_EXP`]: f64::MAX_EXP
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMAX:f64 = 1.7976931348623157e+308_f64;
 
 /// One greater than the minimum possible normal power of 2 exponent.
+///
+/// If <i>x</i>&nbsp;=&nbsp;`MIN_EXP`, then normal numbers
+/// ≥&nbsp;0.5&nbsp;×&nbsp;2<sup><i>x</i></sup>.
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN_EXP:i32 = -1021;
 /// Maximum possible power of 2 exponent.
+///
+/// If <i>x</i>&nbsp;=&nbsp;`MAX_EXP`, then normal numbers
+/// &lt;&nbsp;1&nbsp;×&nbsp;2<sup><i>x</i></sup>.
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMAX_EXP:i32 = 1024;
 
-/// Minimum possible normal power of 10 exponent.
+/// Minimum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
+///
+/// Equal to ceil(log<sub>10</sub>&nbsp;[`MIN_POSITIVE`]).
+///
+/// [`MIN_POSITIVE`]: f64::MIN_POSITIVE
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMIN_10_EXP:i32 = -307;
-/// Maximum possible power of 10 exponent.
+/// Maximum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
+///
+/// Equal to floor(log<sub>10</sub>&nbsp;[`MAX`]).
+///
+/// [`MAX`]: f64::MAX
 #[stable(feature = "assoc_int_consts", since = "1.43.0")]
 pubconstMAX_10_EXP:i32 = 308;