From cea4c278063d43d1473235ba2295f6c0e7678277 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Mon, 19 May 2014 21:53:00 -0700 Subject: [PATCH] core: Spruce up the crate description --- src/libcore/lib.rs | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs index 9f147fafdc2..b7cfddbde90 100644 --- a/src/libcore/lib.rs +++ b/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"]