core: Clarify prelude docs. #4556

src/libcore/cast.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Unsafe casting functions
+
 pub mod rusti {
     #[abi = "rust-intrinsic"]
     #[link_name = "rusti"]

src/libcore/cell.rs

@@ -8,13 +8,17 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! A mutable, nullable memory location
+
 use cast::transmute;
 use option;
 use prelude::*;
 
-/// A dynamic, mutable location.
-///
-/// Similar to a mutable option type, but friendlier.
+/*
+A dynamic, mutable location.
+
+Similar to a mutable option type, but friendlier.
+*/
 
 pub struct Cell<T> {
     mut value: Option<T>

src/libcore/clone.rs

@@ -8,9 +8,20 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/**
-Clonable types are copied with the clone method
+/*! The Clone trait for types that cannot be "implicitly copied"
+
+In Rust, some simple types are "implicitly copyable" and when you
+assign them or pass them as arguments, the receiver will get a copy,
+leaving the original value in place. These types do not require
+allocation to copy and do not have finalizers (i.e. they do not
+contain owned pointers or implement `Drop`), so the compiler considers
+them cheap and safe to copy and automatically implements the `Copy`
+trait for them. For other types copies must be made explicitly,
+by convention implementing the `Clone` trait and calling the
+`clone` method.
+
 */
+
 pub trait Clone {
     fn clone(&self) -> Self;
 }

src/libcore/comm.rs

@@ -8,6 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+Message passing
+*/
+
 use cast;
 use either::{Either, Left, Right};
 use kinds::Owned;

src/libcore/condition.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*! Condition handling */
+
 use prelude::*;
 use task;
 use task::local_data::{local_data_pop, local_data_set};

src/libcore/core.rc

@@ -10,27 +10,39 @@
 
 /*!
 
-The Rust core library
+# The Rust core library
 
 The Rust core library provides runtime features required by the language,
 including the task scheduler and memory allocators, as well as library
 support for Rust built-in types, platform abstractions, and other commonly
 used features.
 
 `core` includes modules corresponding to each of the integer types, each of
-the floating point types, the `bool` type, tuples, characters, strings,
-vectors (`vec`), managed boxes (`managed`), owned boxes (`owned`), and unsafe
-and borrowed pointers (`ptr`).  Additionally, `core` provides task management
-and creation (`task`), communication primitives (`comm` and `pipes`), platform
-abstractions (`os` and `path`), basic I/O abstractions (`io`), common traits
-(`cmp`, `num`, `to_str`), and complete bindings to the C standard library
-(`libc`).
+the floating point types, the `bool` type, tuples, characters, strings
+(`str`), vectors (`vec`), managed boxes (`managed`), owned boxes (`owned`),
+and unsafe and borrowed pointers (`ptr`).  Additionally, `core` provides
+pervasive types (`option` and `result`), task creation and communication
+primitives (`task`, `comm`), platform abstractions (`os` and `path`), basic
+I/O abstractions (`io`), common traits (`kinds`, `ops`, `cmp`, `num`,
+`to_str`), and complete bindings to the C standard library (`libc`).
 
-`core` is linked to all crates by default and its contents imported.
-Implicitly, all crates behave as if they included the following prologue:
+# Core injection and the Rust prelude
+
+`core` is imported at the topmost level of every crate by default, as
+if the first line of each crate was
 
     extern mod core;
-    use core::*;
+
+This means that the contents of core can be accessed from from any context
+with the `core::` path prefix, as in `use core::vec`, `use core::task::spawn`,
+etc.
+
+Additionally, `core` contains a `prelude` module that reexports many of the
+most common core modules, types and traits. The contents of the prelude are
+imported inte every *module* by default.  Implicitly, all modules behave as if
+they contained the following prologue:
+
+    use core::prelude::*;
 
 */
 

src/libcore/prelude.rs

@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-// This file is imported into every module by default.
+//! The Rust prelude. Imported into every module by default.
 
 /* Reexported core operators */
 

src/libcore/rt/mod.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[doc(hidden)];
+
 use libc::c_char;
 
 // Some basic logging