Rollup merge of rust-lang#31520 - steveklabnik:doc_num, r=alexcrichton

This commit does two things:

* Re-works the module-level documentation.
* Cleaning up wording and adding links to where error types are used.

Part of rust-lang#29364

Author: steveklabnik

src/libcore/num/dec2flt/mod.rs

@@ -149,6 +149,13 @@ from_str_float_impl!(f32);
 from_str_float_impl!(f64);
 
 /// An error which can be returned when parsing a float.
+///
+/// This error is used as the error type for the [`FromStr`] implementation
+/// for [`f32`] and [`f64`].
+///
+/// [`FromStr`]: ../str/trait.FromStr.html
+/// [`f32`]: ../primitive.f32.html
+/// [`f64`]: ../primitive.f64.html
 #[derive(Debug, Clone, PartialEq)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct ParseFloatError {

src/libcore/num/mod.rs

@@ -2160,7 +2160,13 @@ impl usize {
         intrinsics::mul_with_overflow }
 }
 
-/// Used for representing the classification of floating point numbers
+/// A classification of floating point numbers.
+///
+/// This `enum` is used as the return type for [`f32::classify()`] and [`f64::classify()`]. See
+/// their documentation for more.
+///
+/// [`f32::classify()`]: ../primitive.f32.html#method.classify
+/// [`f64::classify()`]: ../primitive.f64.html#method.classify
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub enum FpCategory {
@@ -2387,6 +2393,11 @@ fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32)
 }
 
 /// An error which can be returned when parsing an integer.
+///
+/// This error is used as the error type for the `from_str_radix()` functions
+/// on the primitive integer types, such as [`i8::from_str_radix()`].
+///
+/// [`i8::from_str_radix()`]: ../std/primitive.i8.html#method.from_str_radix
 #[derive(Debug, Clone, PartialEq)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct ParseIntError { kind: IntErrorKind }

src/libstd/num/mod.rs

@@ -8,10 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Numeric traits and functions for generic mathematics
+//! Additional functionality for numerics.
 //!
-//! These are implemented for the primitive numeric types in `std::{u8, u16,
-//! u32, u64, usize, i8, i16, i32, i64, isize, f32, f64}`.
+//! This module provides some extra types that are useful when doing numerical
+//! work. See the individual documentation for each piece for more information.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 #![allow(missing_docs)]