From 113fbfc795951a10f6c0b08563944bfb6a965956 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Sun, 24 Mar 2013 18:38:17 -0700 Subject: [PATCH 1/2] core: Clarify prelude docs. #4556 --- src/libcore/core.rc | 34 +++++++++++++++++++++++----------- src/libcore/prelude.rs | 2 +- 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/src/libcore/core.rc b/src/libcore/core.rc index f38227de4972..35a016c3cb09 100644 --- a/src/libcore/core.rc +++ b/src/libcore/core.rc @@ -10,7 +10,7 @@ /*! -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 @@ -18,19 +18,31 @@ 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::*; */ diff --git a/src/libcore/prelude.rs b/src/libcore/prelude.rs index d0307c8bf70d..7166ffbd3d3b 100644 --- a/src/libcore/prelude.rs +++ b/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 */ From e5f8026ebab867547514677bf9d7c7870a4345ad Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Sun, 24 Mar 2013 18:59:04 -0700 Subject: [PATCH 2/2] core: Make sure every module at least has a one-line description --- src/libcore/cast.rs | 2 ++ src/libcore/cell.rs | 10 +++++++--- src/libcore/clone.rs | 15 +++++++++++++-- src/libcore/comm.rs | 4 ++++ src/libcore/condition.rs | 2 ++ src/libcore/rt/mod.rs | 2 ++ 6 files changed, 30 insertions(+), 5 deletions(-) diff --git a/src/libcore/cast.rs b/src/libcore/cast.rs index f752f52ce539..c1c7bd237702 100644 --- a/src/libcore/cast.rs +++ b/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"] diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs index bf5f93159381..2c29dbd2e942 100644 --- a/src/libcore/cell.rs +++ b/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 { mut value: Option diff --git a/src/libcore/clone.rs b/src/libcore/clone.rs index af44f68601bc..7b86355c91e5 100644 --- a/src/libcore/clone.rs +++ b/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; } diff --git a/src/libcore/comm.rs b/src/libcore/comm.rs index 6dadca8dc57b..f749d46bcab1 100644 --- a/src/libcore/comm.rs +++ b/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; diff --git a/src/libcore/condition.rs b/src/libcore/condition.rs index 767b6ecfad4b..6b5d8b91439e 100644 --- a/src/libcore/condition.rs +++ b/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}; diff --git a/src/libcore/rt/mod.rs b/src/libcore/rt/mod.rs index 04891a1673c0..a7b3fb1355c7 100644 --- a/src/libcore/rt/mod.rs +++ b/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