Clean up the prelude docs

This mostly brings them in line with existing linking convention, but
also has some minor re-wording.

The text at the top has been re-focused, by starting out with what the
prelude does, rather than starting from injecting std.

Also, it now mentions that other preludes exist.

Part of https://github.com/rust-lang/rust/issues/29369

2 files changed, 115 insertions, 96 deletions

diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs
index 08227cfb353..3ff1798159e 100644
--- a/src/libstd/prelude/mod.rs
+++ b/src/libstd/prelude/mod.rs
@@ -10,119 +10,136 @@
 
 //! The Rust Prelude
 //!
-//! Because `std` is required by most serious Rust software, it is
-//! imported at the topmost level of every crate by default, as if
-//! each crate contains the following:
+//! Rust comes with a variety of things in its standard library. However, if
+//! you had to manually import every single thing that you used, it would be
+//! very verbose. But importing a lot of things that a program never uses isn't
+//! good either. A balance needs to be struck.
+//!
+//! The *prelude* is the list of things that Rust automatically imports into
+//! every Rust program. It's kept as small as possible, and is focused on
+//! things, particuarly traits, which are used in almost every single Rust
+//! program.
+//!
+//! On a technical level, Rust inserts
 //!
 //! ```ignore
 //! extern crate std;
 //! ```
 //!
-//! This means that the contents of std can be accessed from any context
-//! with the `std::` path prefix, as in `use std::vec`, `use std::thread::spawn`,
-//! etc.
-//!
-//! Additionally, `std` contains a versioned *prelude* that reexports many of the
-//! most common traits, types, and functions. *The contents of the prelude are
-//! imported into every module by default*.  Implicitly, all modules behave as if
-//! they contained the following [`use` statement][book-use]:
-//!
-//! [book-use]: ../../book/crates-and-modules.html#importing-modules-with-use
+//! into the crate root of every crate, and 
 //!
 //! ```ignore
 //! use std::prelude::v1::*;
 //! ```
 //!
-//! The prelude is primarily concerned with exporting *traits* that
-//! are so pervasive that they would be onerous to import for every use,
-//! particularly those that are commonly mentioned in [generic type
-//! bounds][book-traits].
+//! into every module.
+//!
+//! # Other preludes
+//!
+//! Preludes can be seen as a pattern to make using multiple types more
+//! convenient. As such, you'll find other preludes in the standard library,
+//! such as [`std::io::prelude`]. Various libraries in the Rust ecosystem may
+//! also define their own preludes.
+//!
+//! [`std::io::prelude`]: ../io/prelude/index.html
+//!
+//! The differece between 'the prelude' and these other preludes is that they
+//! are not automatically `use`'d, and must be imported manually. This is still
+//! easier than importing all of their consitutent components.
+//!
+//! # Prelude contents
 //!
 //! The current version of the prelude (version 1) lives in
-//! [`std::prelude::v1`](v1/index.html), and reexports the following.
+//! [`std::prelude::v1`], and reexports the following.
 //!
-//! * `std::marker::`{
-//!     [`Copy`](../marker/trait.Copy.html),
-//!     [`Send`](../marker/trait.Send.html),
-//!     [`Sized`](../marker/trait.Sized.html),
-//!     [`Sync`](../marker/trait.Sync.html)
-//!   }.
-//!   The marker traits indicate fundamental properties of types.
-//! * `std::ops::`{
-//!     [`Drop`](../ops/trait.Drop.html),
-//!     [`Fn`](../ops/trait.Fn.html),
-//!     [`FnMut`](../ops/trait.FnMut.html),
-//!     [`FnOnce`](../ops/trait.FnOnce.html)
-//!   }.
-//!   The [destructor][book-dtor] trait and the
-//!   [closure][book-closures] traits, reexported from the same
-//!   [module that also defines overloaded
-//!   operators](../ops/index.html).
-//! * `std::mem::`[`drop`](../mem/fn.drop.html).
-//!   A convenience function for explicitly dropping a value.
-//! * `std::boxed::`[`Box`](../boxed/struct.Box.html).
-//!   The owned heap pointer.
-//! * `std::borrow::`[`ToOwned`](../borrow/trait.ToOwned.html).
-//!   The conversion trait that defines `to_owned`, the generic method
-//!   for creating an owned type from a borrowed type.
-//! * `std::clone::`[`Clone`](../clone/trait.Clone.html).
-//!   The ubiquitous trait that defines `clone`, the method for
-//!   producing copies of values that are consider expensive to copy.
-//! * `std::cmp::`{
-//!     [`PartialEq`](../cmp/trait.PartialEq.html),
-//!     [`PartialOrd`](../cmp/trait.PartialOrd.html),
-//!     [`Eq`](../cmp/trait.Eq.html),
-//!     [`Ord`](../cmp/trait.Ord.html)
-//!   }.
-//!   The comparison traits, which implement the comparison operators
-//!   and are often seen in trait bounds.
-//! * `std::convert::`{
-//!     [`AsRef`](../convert/trait.AsRef.html),
-//!     [`AsMut`](../convert/trait.AsMut.html),
-//!     [`Into`](../convert/trait.Into.html),
-//!     [`From`](../convert/trait.From.html)
-//!   }.
-//!   Generic conversions, used by savvy API authors to create
-//!   overloaded methods.
-//! * `std::default::`[`Default`](../default/trait.Default.html).
-//!   Types that have default values.
-//! * `std::iter::`{
-//!     [`Iterator`](../iter/trait.Iterator.html),
-//!     [`Extend`](../iter/trait.Extend.html),
-//!     [`IntoIterator`](../iter/trait.IntoIterator.html),
-//!     [`DoubleEndedIterator`](../iter/trait.DoubleEndedIterator.html),
-//!     [`ExactSizeIterator`](../iter/trait.ExactSizeIterator.html)
-//!   }.
-//!   [Iterators][book-iter].
-//! * `std::option::Option::`{
-//!     [`self`](../option/enum.Option.html),
-//!     [`Some`](../option/enum.Option.html),
-//!     [`None`](../option/enum.Option.html)
-//!   }.
-//!   The ubiquitous `Option` type and its two [variants][book-enums],
-//!   `Some` and `None`.
-//! * `std::result::Result::`{
-//!     [`self`](../result/enum.Result.html),
-//!     [`Ok`](../result/enum.Result.html),
-//!     [`Err`](../result/enum.Result.html)
-//!   }.
-//!   The ubiquitous `Result` type and its two [variants][book-enums],
-//!   `Ok` and `Err`.
-//! * `std::slice::`[`SliceConcatExt`](../slice/trait.SliceConcatExt.html).
-//!   An unstable extension to slices that shouldn't have to exist.
-//! * `std::string::`{
-//!     [`String`](../string/struct.String.html),
-//!     [`ToString`](../string/trait.ToString.html)
-//!   }.
-//!   Heap allocated strings.
-//! * `std::vec::`[`Vec`](../vec/struct.Vec.html).
-//!   Heap allocated vectors.
+//! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`]}. The marker
+//!   traits indicate fundamental properties of types.
+//! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}. Various
+//!   operations for both destuctors and overloading `()`.
+//! * [`std::mem`]::[`drop`], a convenience function for explicitly dropping a
+//!   value.
+//! * [`std::boxed`]::[`Box`], a way to allocate values on the heap.
+//! * [`std::borrow`]::[`ToOwned`], The conversion trait that defines
+//!   [`to_owned()`], the generic method for creating an owned type from a
+//!   borrowed type.
+//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines [`clone()`],
+//!   the method for producing a copy of a value.
+//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }. The
+//!   comparison traits, which implement the comparison operators and are often
+//!   seen in trait bounds.
+//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}. Generic
+//!   conversions, used by savvy API authors to create overloaded methods.
+//! * [`std::default`]::[`Default`], types that have default values.
+//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`],
+//!   [`DoubleEndedIterator`], [`ExactSizeIterator`]}. Iterators of various
+//!   kinds.
+//! * [`std::option`]::[`Option`]::{`self`, `Some`, `None`}. A type which
+//!   expresses the presence or absence of a value. This type is so commonly
+//!   used, its variants are also exported.
+//! * [`std::result`]::[`Result`]::{`self`, `Ok`, `Err`}. A type for functions
+//!   that may succeed or fail. Like [`Option`], its variants are exported as
+//!   well.
+//! * [`std::slice`]::[`SliceConcatExt`], a trait that exists for technical
+//!   reasons, but shouldn't have to exist. It provides a few useful methods on
+//!   slices.
+//! * [`std::string`]::{[`String`], [`ToString`]}, heap allocated strings.
+//! * [`std::vec`]::[`Vec`](../vec/struct.Vec.html), a growable, heap-allocated
+//!   vector.
 //!
-//! [book-traits]: ../../book/traits.html
+//! [`AsMut`]: ../convert/trait.AsMut.html
+//! [`AsRef`]: ../convert/trait.AsRef.html
+//! [`Box`]: ../boxed/struct.Box.html
+//! [`Clone`]: ../clone/trait.Clone.html
+//! [`Copy`]: ../marker/trait.Copy.html
+//! [`Default`]: ../default/trait.Default.html
+//! [`DoubleEndedIterator`]: ../iter/trait.DoubleEndedIterator.html
+//! [`Drop`]: ../ops/trait.Drop.html
+//! [`Eq`]: ../cmp/trait.Eq.html
+//! [`ExactSizeIterator`]: ../iter/trait.ExactSizeIterator.html
+//! [`Extend`]: ../iter/trait.Extend.html
+//! [`FnMut`]: ../ops/trait.FnMut.html
+//! [`FnOnce`]: ../ops/trait.FnOnce.html
+//! [`Fn`]: ../ops/trait.Fn.html
+//! [`From`]: ../convert/trait.From.html
+//! [`IntoIterator`]: ../iter/trait.IntoIterator.html
+//! [`Into`]: ../convert/trait.Into.html
+//! [`Iterator`]: ../iter/trait.Iterator.html
+//! [`Option`]: ../option/enum.Option.html
+//! [`Ord`]: ../cmp/trait.Ord.html
+//! [`PartialEq`]: ../cmp/trait.PartialEq.html
+//! [`PartialOrd`]: ../cmp/trait.PartialOrd.html
+//! [`Result`]: ../result/enum.Result.html
+//! [`Send`]: ../marker/trait.Send.html
+//! [`Sized`]: ../marker/trait.Sized.html
+//! [`SliceConcatExt`]: ../slice/trait.SliceConcatExt.html
+//! [`String`]: ../string/struct.String.html
+//! [`Sync`]: ../marker/trait.Sync.html
+//! [`ToOwned`]: ../borrow/trait.ToOwned.html
+//! [`ToString`]: ../string/trait.ToString.html
+//! [`Vec`]: ../vec/struct.Vec.html
+//! [`clone()`]: ../clone/trait.Clone.html#tymethod.clone
+//! [`drop`]: ../mem/fn.drop.html
+//! [`std::borrow`]: ../borrow/index.html
+//! [`std::boxed`]: ../boxed/index.html
+//! [`std::clone`]: ../clone/index.html
+//! [`std::cmp`]: ../cmp/index.html
+//! [`std::convert`]: ../convert/index.html
+//! [`std::default`]: ../default/index.html
+//! [`std::iter`]: ../iter/index.html
+//! [`std::marker`]: ../marker/index.html
+//! [`std::mem`]: ../mem/index.html
+//! [`std::ops`]: ../ops/index.html
+//! [`std::option`]: ../option/index.html
+//! [`std::prelude::v1`]: v1/index.html
+//! [`std::result`]: ../result/index.html
+//! [`std::slice`]: ../slice/index.html
+//! [`std::string`]: ../string/index.html
+//! [`std::vec`]: ../vec/index.html
+//! [`to_owned()`]: ../borrow/trait.ToOwned.html#tymethod.to_owned
 //! [book-closures]: ../../book/closures.html
 //! [book-dtor]: ../../book/drop.html
-//! [book-iter]: ../../book/iterators.html
 //! [book-enums]: ../../book/enums.html
+//! [book-iter]: ../../book/iterators.html
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
diff --git a/src/libstd/prelude/v1.rs b/src/libstd/prelude/v1.rs
index 46c0103e087..9ca5b445c86 100644
--- a/src/libstd/prelude/v1.rs
+++ b/src/libstd/prelude/v1.rs
@@ -9,6 +9,8 @@
 // except according to those terms.
 
 //! The first version of the prelude of The Rust Standard Library.
+//!
+//! See the [module-level documentation](../index.html) for more.
 
 #![stable(feature = "rust1", since = "1.0.0")]