core: Add a crate doc block

Author: alexcrichton

src/libcore/lib.rs

@@ -9,6 +9,27 @@
 // except according to those terms.
 
 //! The Rust core library
+//!
+//! This library is meant to represent the core functionality of rust that is
+//! maximally portable to other platforms. To that exent, 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:
+//!
+//! * `memcpy`, `memcmp`, `memset` - These are core memory routines which are
+//!   often generated by LLVM. Additionally, this library can make explicit
+//!   calls to these funcitons. Their signatures are the same as found in C.
+//!
+//! * `rust_begin_unwind` - This function takes three arguments, a
+//!   `&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"]