core: Spruce up the crate description

Author: brson

src/libcore/lib.rs

@@ -8,12 +8,28 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The Rust core library
+//! The Rust Core Library
 //!
-//! This library is meant to represent the core functionality of rust that is
-//! maximally portable to other platforms. To that extent, this library has no
-//! knowledge of things like allocation, threads, I/O, etc. This library is
-//! built on the assumption of a few existing symbols:
+//! The Rust Core Library is the dependency-free foundation of [The
+//! Rust Standard Library](../std/index.html). It is the portable glue
+//! between the language and its libraries, defining the intrinsic and
+//! primitive building blocks of all Rust code. It links to no
+//! upstream libraries, no system libraries, no libc.
+//!
+//! The core library is *minimal*: it isn't even aware of heap allocation,
+//! nor does it provide concurrency or I/O. These things require
+//! platform integration, and this library is platform-oblivious.
+//!
+//! *It is not recommended to use the core library*. The stable
+//! functionality of libcore is reexported from the
+//! [standard library](../std/index.html). The composition of this library is
+//! subject to change over time; only the interface exposed through libstd is
+//! intended to be stable.
+//!
+//! # How to use the core library
+//!
+// TODO: Fill me in with more detail when the interface settles
+//! This library is built on the assumption of a few existing symbols:
 //!
 //! * `memcpy`, `memcmp`, `memset` - These are core memory routines which are
 //!   often generated by LLVM. Additionally, this library can make explicit
@@ -23,16 +39,11 @@
 //!   distribution.
 //!
 //! * `rust_begin_unwind` - This function takes three arguments, a
-//!   `&fmt::Arguments`, a `&str`, and a `uint. These three arguments dictate
+//!   `&fmt::Arguments`, a `&str`, and a `uint`. These three arguments dictate
 //!   the failure message, the file at which failure was invoked, and the line.
 //!   It is up to consumers of this core library to define this failure
 //!   function; it is only required to never return.
 //!
-//! Currently, it is *not* recommended to use the core library. The stable
-//! functionality of libcore is exported directly into the
-//! [standard library](../std/index.html). The composition of this library is
-//! subject to change over time, only the interface exposed through libstd is
-//! intended to be stable.
 
 #![crate_id = "core#0.11.0-pre"]
 #![license = "MIT/ASL2"]