Expand documentation for `FpCategory`.

I intend these changes to be helpful to readers who are not yet familiar
with the quirks of floating-point numbers. Additionally, I felt it was
misleading to describe `Nan` as being the result of division by zero,
since most divisions by zero (except for 0/0) produce `Infinite` floats,
so I moved that remark to the `Infinite` variant with adjustment.

The first sentence of the `Nan` documentation is copied from `f32`;
I followed the example of the `f64` documentation by referring to `f32`
for general concepts, rather than duplicating the text.

1 files changed, 22 insertions, 4 deletions

diff --git a/library/core/src/num/mod.rs b/library/core/src/num/mod.rs
index 09b7418bec0..360ca9b700b 100644
--- a/library/core/src/num/mod.rs
+++ b/library/core/src/num/mod.rs
@@ -778,23 +778,41 @@ impl usize {
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub enum FpCategory {
-    /// "Not a Number", often obtained by dividing by zero.
+    /// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`.
+    ///
+    /// See [the documentation for `f32`](f32) for more information on the unusual properties
+    /// of NaN.
     #[stable(feature = "rust1", since = "1.0.0")]
     Nan,
 
-    /// Positive or negative infinity.
+    /// Positive or negative infinity, which often results from dividing a nonzero number
+    /// by zero.
     #[stable(feature = "rust1", since = "1.0.0")]
     Infinite,
 
     /// Positive or negative zero.
+    ///
+    /// See [the documentation for `f32`](f32) for more information on the signedness of zeroes.
     #[stable(feature = "rust1", since = "1.0.0")]
     Zero,
 
-    /// De-normalized floating point representation (less precise than `Normal`).
+    /// “Subnormal” or “denormal” floating point representation (less precise, relative to
+    /// their magnitude, than [`Normal`]).
+    ///
+    /// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all
+    /// [`Normal`] numbers.
+    ///
+    /// [`Normal`]: Self::Normal
+    /// [`Zero`]: Self::Zero
     #[stable(feature = "rust1", since = "1.0.0")]
     Subnormal,
 
-    /// A regular floating point number.
+    /// A regular floating point number, not any of the exceptional categories.
+    ///
+    /// The smallest positive normal numbers are [`f32::MIN_POSITIVE`] and [`f64::MIN_POSITIVE`],
+    /// and the largest positive normal numbers are [`f32::MAX`] and [`f64::MAX`]. (Unlike signed
+    /// integers, floating point numbers are symmetric in their range, so negating any of these
+    /// constants will produce their negative counterpart.)
     #[stable(feature = "rust1", since = "1.0.0")]
     Normal,
 }