std: Rewrite crate docs

[rust.git] / src / libstd / prelude.rs

diff --git a/src/libstd/prelude.rs b/src/libstd/prelude.rs
index a44b23c42494eb7baf96bf89a9095e51b792022f..963f2c8d2c3129cb987431982f452d5d91d21b9d 100644 (file)
--- a/src/libstd/prelude.rs
+++ b/src/libstd/prelude.rs
@@ -8,16 +8,34 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/*!
-
-The standard module imported by default into all Rust modules
-
-Many programming languages have a 'prelude': a particular subset of the
-libraries that come with the language. Every program imports the prelude by
-default. The prelude imports various core parts of the library that are
-generally useful to many Rust programs.
-
-*/
+//! # 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 the
+//! first line of each crate was
+//!
+//! ```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::task::spawn`,
+//! etc.
+//!
+//! Additionally, `std` contains a `prelude` module 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 prologue:
+//!
+//! ```ignore
+//! use std::prelude::*;
+//! ```
+//!
+//! The prelude is primarily concerned with exporting *traits* that are so
+//! pervasive that it would be obnoxious to import for every use, particularly
+//! those that define methods on primitive types. It does include a few
+//! particularly useful standalone functions, like `from_str`, `range`, and
+//! `drop`, `spawn`, and `channel`.
 
 // Reexported core operators
 pub use kinds::{Copy, Send, Sized, Share};