diff options
40 files changed, 478 insertions, 344 deletions
diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index f5a27565ef7..4378d0804df 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -8,9 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Utilities for slice manipulation +//! A dynamically-sized view into a contiguous sequence, `[T]`. //! -//! The `slice` module contains useful code to help work with slice values. //! Slices are a view into a block of memory represented as a pointer and a //! length. //! @@ -78,7 +77,8 @@ //! iterators. //! * Further methods that return iterators are `.split()`, `.splitn()`, //! `.chunks()`, `.windows()` and more. -#![doc(primitive = "slice")] +//! +//! *[See also the slice primitive type](../primitive.slice.html).* #![stable(feature = "rust1", since = "1.0.0")] // Many of the usings in this module are only used in the test configuration. diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs index cb6613998b4..25a3441fd5b 100644 --- a/src/libcollections/str.rs +++ b/src/libcollections/str.rs @@ -8,43 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Unicode string manipulation (the `str` type). +//! Unicode string slices //! -//! Rust's `str` type is one of the core primitive types of the language. `&str` -//! is the borrowed string type. This type of string can only be created from -//! other strings, unless it is a `&'static str` (see below). It is not possible -//! to move out of borrowed strings because they are owned elsewhere. -//! -//! # Examples -//! -//! Here's some code that uses a `&str`: -//! -//! ``` -//! let s = "Hello, world."; -//! ``` -//! -//! This `&str` is a `&'static str`, which is the type of string literals. -//! They're `'static` because literals are available for the entire lifetime of -//! the program. -//! -//! You can get a non-`'static` `&str` by taking a slice of a `String`: -//! -//! ``` -//! let some_string = "Hello, world.".to_string(); -//! let s = &some_string; -//! ``` -//! -//! # Representation -//! -//! Rust's string type, `str`, is a sequence of Unicode scalar values encoded as -//! a stream of UTF-8 bytes. All [strings](../../reference.html#literals) are -//! guaranteed to be validly encoded UTF-8 sequences. Additionally, strings are -//! not null-terminated and can thus contain null bytes. -//! -//! The actual representation of `str`s have direct mappings to slices: `&str` -//! is the same as `&[u8]`. +//! *[See also the `str` primitive type](../primitive.str.html).* + -#![doc(primitive = "str")] #![stable(feature = "rust1", since = "1.0.0")] // Many of the usings in this module are only used in the test configuration. diff --git a/src/libcore/array.rs b/src/libcore/array.rs index a9b240de30b..cfe22b89178 100644 --- a/src/libcore/array.rs +++ b/src/libcore/array.rs @@ -11,8 +11,9 @@ //! Implementations of things like `Eq` for fixed-length arrays //! up to a certain length. Eventually we should able to generalize //! to all lengths. +//! +//! *[See also the array primitive type](../primitive.array.html).* -#![doc(primitive = "array")] #![unstable(feature = "fixed_size_array", reason = "traits and impls are better expressed through generic \ integer constants")] diff --git a/src/libcore/char.rs b/src/libcore/char.rs index 12aa06667a1..88aa805668c 100644 --- a/src/libcore/char.rs +++ b/src/libcore/char.rs @@ -13,7 +13,6 @@ //! For more details, see ::rustc_unicode::char (a.k.a. std::char) #![allow(non_snake_case)] -#![doc(primitive = "char")] #![stable(feature = "core_char", since = "1.2.0")] use iter::Iterator; diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs index 030d2a33f8f..ef2a33c37dd 100644 --- a/src/libcore/lib.rs +++ b/src/libcore/lib.rs @@ -154,10 +154,6 @@ pub mod str; pub mod hash; pub mod fmt; -#[doc(primitive = "bool")] -mod bool { -} - // note: does not need to be public mod tuple; diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index 9270d3f12b0..6b4424093b4 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -10,7 +10,6 @@ //! Operations and constants for 32-bits floats (`f32` type) -#![doc(primitive = "f32")] // FIXME: MIN_VALUE and MAX_VALUE literals are parsed as -inf and inf #14353 #![allow(overflowing_literals)] diff --git a/src/libcore/num/f64.rs b/src/libcore/num/f64.rs index d2ab2695f5e..fa7aa2ab5ce 100644 --- a/src/libcore/num/f64.rs +++ b/src/libcore/num/f64.rs @@ -10,7 +10,6 @@ //! Operations and constants for 64-bits floats (`f64` type) -#![doc(primitive = "f64")] // FIXME: MIN_VALUE and MAX_VALUE literals are parsed as -inf and inf #14353 #![allow(overflowing_literals)] diff --git a/src/libcore/num/i16.rs b/src/libcore/num/i16.rs index 5ea60d0d96d..dacb4ebcdfa 100644 --- a/src/libcore/num/i16.rs +++ b/src/libcore/num/i16.rs @@ -11,6 +11,5 @@ //! Operations and constants for signed 16-bits integers (`i16` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i16")] int_module! { i16, 16 } diff --git a/src/libcore/num/i32.rs b/src/libcore/num/i32.rs index 7d9faa998c1..250d66de70b 100644 --- a/src/libcore/num/i32.rs +++ b/src/libcore/num/i32.rs @@ -11,6 +11,5 @@ //! Operations and constants for signed 32-bits integers (`i32` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i32")] int_module! { i32, 32 } diff --git a/src/libcore/num/i64.rs b/src/libcore/num/i64.rs index 5a70911387b..5ed21d7246c 100644 --- a/src/libcore/num/i64.rs +++ b/src/libcore/num/i64.rs @@ -11,6 +11,5 @@ //! Operations and constants for signed 64-bits integers (`i64` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i64")] int_module! { i64, 64 } diff --git a/src/libcore/num/i8.rs b/src/libcore/num/i8.rs index 1d7d78ffa6c..0394c12d5c4 100644 --- a/src/libcore/num/i8.rs +++ b/src/libcore/num/i8.rs @@ -11,6 +11,5 @@ //! Operations and constants for signed 8-bits integers (`i8` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i8")] int_module! { i8, 8 } diff --git a/src/libcore/num/isize.rs b/src/libcore/num/isize.rs index 2cdfe03eafe..066cb10cce2 100644 --- a/src/libcore/num/isize.rs +++ b/src/libcore/num/isize.rs @@ -11,7 +11,6 @@ //! Operations and constants for pointer-sized signed integers (`isize` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "isize")] #[cfg(target_pointer_width = "32")] int_module! { isize, 32 } diff --git a/src/libcore/num/u16.rs b/src/libcore/num/u16.rs index 21635799a77..ecf79944848 100644 --- a/src/libcore/num/u16.rs +++ b/src/libcore/num/u16.rs @@ -11,6 +11,5 @@ //! Operations and constants for unsigned 16-bits integers (`u16` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u16")] uint_module! { u16, i16, 16 } diff --git a/src/libcore/num/u32.rs b/src/libcore/num/u32.rs index 7d520770503..b0682b55ac0 100644 --- a/src/libcore/num/u32.rs +++ b/src/libcore/num/u32.rs @@ -11,6 +11,5 @@ //! Operations and constants for unsigned 32-bits integers (`u32` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u32")] uint_module! { u32, i32, 32 } diff --git a/src/libcore/num/u64.rs b/src/libcore/num/u64.rs index f10822077dc..dbc6a64a905 100644 --- a/src/libcore/num/u64.rs +++ b/src/libcore/num/u64.rs @@ -11,6 +11,5 @@ //! Operations and constants for unsigned 64-bits integer (`u64` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u64")] uint_module! { u64, i64, 64 } diff --git a/src/libcore/num/u8.rs b/src/libcore/num/u8.rs index 3d6922b07b1..bf9347ca62c 100644 --- a/src/libcore/num/u8.rs +++ b/src/libcore/num/u8.rs @@ -11,6 +11,5 @@ //! Operations and constants for unsigned 8-bits integers (`u8` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u8")] uint_module! { u8, i8, 8 } diff --git a/src/libcore/num/usize.rs b/src/libcore/num/usize.rs index 6fd23425e4d..67e3c954ab6 100644 --- a/src/libcore/num/usize.rs +++ b/src/libcore/num/usize.rs @@ -11,6 +11,5 @@ //! Operations and constants for pointer-sized unsigned integers (`usize` type) #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "usize")] uint_module! { usize, isize, ::isize::BITS } diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs index 7b33a41f955..13d95e9ab1a 100644 --- a/src/libcore/ptr.rs +++ b/src/libcore/ptr.rs @@ -10,84 +10,11 @@ // FIXME: talk about offset, copy_memory, copy_nonoverlapping_memory -//! Operations on raw pointers, `*const T`, and `*mut T`. +//! Raw, unsafe pointers, `*const T`, and `*mut T` //! -//! Working with raw pointers in Rust is uncommon, -//! typically limited to a few patterns. -//! -//! Use the `null` function to create null pointers, and the `is_null` method -//! of the `*const T` type to check for null. The `*const T` type also defines -//! the `offset` method, for pointer math. -//! -//! # Common ways to create raw pointers -//! -//! ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`). -//! -//! ``` -//! let my_num: i32 = 10; -//! let my_num_ptr: *const i32 = &my_num; -//! let mut my_speed: i32 = 88; -//! let my_speed_ptr: *mut i32 = &mut my_speed; -//! ``` -//! -//! To get a pointer to a boxed value, dereference the box: -//! -//! ``` -//! let my_num: Box<i32> = Box::new(10); -//! let my_num_ptr: *const i32 = &*my_num; -//! let mut my_speed: Box<i32> = Box::new(88); -//! let my_speed_ptr: *mut i32 = &mut *my_speed; -//! ``` -//! -//! This does not take ownership of the original allocation -//! and requires no resource management later, -//! but you must not use the pointer after its lifetime. -//! -//! ## 2. Consume a box (`Box<T>`). -//! -//! The `into_raw` function consumes a box and returns -//! the raw pointer. It doesn't destroy `T` or deallocate any memory. -//! -//! ``` -//! # #![feature(box_raw)] -//! let my_speed: Box<i32> = Box::new(88); -//! let my_speed: *mut i32 = Box::into_raw(my_speed); -//! -//! // By taking ownership of the original `Box<T>` though -//! // we are obligated to put it together later to be destroyed. -//! unsafe { -//! drop(Box::from_raw(my_speed)); -//! } -//! ``` -//! -//! Note that here the call to `drop` is for clarity - it indicates -//! that we are done with the given value and it should be destroyed. -//! -//! ## 3. Get it from C. -//! -//! ``` -//! # #![feature(libc)] -//! extern crate libc; -//! -//! use std::mem; -//! -//! fn main() { -//! unsafe { -//! let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>() as libc::size_t) as *mut i32; -//! if my_num.is_null() { -//! panic!("failed to allocate memory"); -//! } -//! libc::free(my_num as *mut libc::c_void); -//! } -//! } -//! ``` -//! -//! Usually you wouldn't literally use `malloc` and `free` from Rust, -//! but C APIs hand out a lot of pointers generally, so are a common source -//! of raw pointers in Rust. +//! *[See also the pointer primitive types](../primitive.pointer.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "pointer")] use mem; use clone::Clone; diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs index 2c6acbf9157..9339f232e91 100644 --- a/src/libcore/slice.rs +++ b/src/libcore/slice.rs @@ -13,7 +13,6 @@ //! For more details `std::slice`. #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "slice")] // How this module is organized. // diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 8683689bbbe..5269cce1744 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -12,7 +12,6 @@ //! //! For more details, see std::str -#![doc(primitive = "str")] #![stable(feature = "rust1", since = "1.0.0")] use self::pattern::Pattern; diff --git a/src/libcore/tuple.rs b/src/libcore/tuple.rs index ba6a7c4a5fe..6c5ff222323 100644 --- a/src/libcore/tuple.rs +++ b/src/libcore/tuple.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations on tuples +//! A finite heterogeneous sequence, `(T, U, ..)` //! //! To access a single element of a tuple one can use the `.0` //! field access syntax. @@ -28,7 +28,6 @@ //! * `Default` #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "tuple")] use clone::Clone; use cmp::*; diff --git a/src/librustc_unicode/char.rs b/src/librustc_unicode/char.rs index 2596620d39d..42c19ee6a20 100644 --- a/src/librustc_unicode/char.rs +++ b/src/librustc_unicode/char.rs @@ -8,15 +8,15 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Character manipulation (`char` type, Unicode Scalar Value) +//! A Unicode scalar value //! //! This module provides the `CharExt` trait, as well as its //! implementation for the primitive `char` type, in order to allow //! basic character manipulation. //! -//! A `char` actually represents a -//! *[Unicode Scalar -//! Value](http://www.unicode.org/glossary/#unicode_scalar_value)*, as it can +//! A `char` represents a +//! *[Unicode scalar +//! value](http://www.unicode.org/glossary/#unicode_scalar_value)*, as it can //! contain any Unicode code point except high-surrogate and low-surrogate code //! points. //! @@ -24,9 +24,10 @@ //! (inclusive) are allowed. A `char` can always be safely cast to a `u32`; //! however the converse is not always true due to the above range limits //! and, as such, should be performed via the `from_u32` function. +//! +//! *[See also the `char` primitive type](../primitive.char.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "char")] use core::char::CharExt as C; use core::option::Option::{self, Some, None}; diff --git a/src/libstd/array.rs b/src/libstd/array.rs deleted file mode 100644 index 0dfcc72e379..00000000000 --- a/src/libstd/array.rs +++ /dev/null @@ -1,55 +0,0 @@ -// Copyright 2015 The Rust Project Developers. See the COPYRIGHT -// file at the top-level directory of this distribution and at -// http://rust-lang.org/COPYRIGHT. -// -// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or -// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license -// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your -// option. This file may not be copied, modified, or distributed -// except according to those terms. - -//! A fixed-size array is denoted `[T; N]` for the element type `T` and -//! the compile time constant size `N`. The size must be zero or positive. -//! -//! Arrays values are created either with an explicit expression that lists -//! each element: `[x, y, z]` or a repeat expression: `[x; N]`. The repeat -//! expression requires that the element type is `Copy`. -//! -//! The type `[T; N]` is `Copy` if `T: Copy`. -//! -//! Arrays of sizes from 0 to 32 (inclusive) implement the following traits -//! if the element type allows it: -//! -//! - `Clone` -//! - `Debug` -//! - `IntoIterator` (implemented for `&[T; N]` and `&mut [T; N]`) -//! - `PartialEq`, `PartialOrd`, `Ord`, `Eq` -//! - `Hash` -//! - `AsRef`, `AsMut` -//! -//! Arrays dereference to [slices (`[T]`)][slice], so their methods can be called -//! on arrays. -//! -//! [slice]: primitive.slice.html -//! -//! Rust does not currently support generics over the size of an array type. -//! -//! # Examples -//! -//! ``` -//! let mut array: [i32; 3] = [0; 3]; -//! -//! array[1] = 1; -//! array[2] = 2; -//! -//! assert_eq!([1, 2], &array[1..]); -//! -//! // This loop prints: 0 1 2 -//! for x in &array { -//! print!("{} ", x); -//! } -//! -//! ``` -//! - -#![doc(primitive = "array")] diff --git a/src/libstd/bool.rs b/src/libstd/bool.rs deleted file mode 100644 index df703b3e43e..00000000000 --- a/src/libstd/bool.rs +++ /dev/null @@ -1,14 +0,0 @@ -// Copyright 2013 The Rust Project Developers. See the COPYRIGHT -// file at the top-level directory of this distribution and at -// http://rust-lang.org/COPYRIGHT. -// -// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or -// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license -// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your -// option. This file may not be copied, modified, or distributed -// except according to those terms. - -//! The boolean type - -#![doc(primitive = "bool")] -#![stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index fa90670acfb..82bc1314ad5 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -415,12 +415,10 @@ pub mod __rand { pub use rand::{thread_rng, ThreadRng, Rng}; } -// Modules that exist purely to document + host impl docs for primitive types - -mod array; -mod bool; -mod unit; -mod tuple; +// Include a number of private modules that exist solely to provide +// the rustdoc documentation for primitive types. Using `include!` +// because rustdoc only looks for these modules at the crate level. +include!("primitive_docs.rs"); // A curious inner-module that's not exported that contains the binding // 'std' so that macro-expanded references to std::error and such diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs index 10cdc0c5833..b8a70d756ef 100644 --- a/src/libstd/num/f32.rs +++ b/src/libstd/num/f32.rs @@ -8,11 +8,13 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for 32-bits floats (`f32` type) +//! The 32-bit floating point type. +//! +//! *[See also the `f32` primitive type](../primitive.f32.html).* #![stable(feature = "rust1", since = "1.0.0")] #![allow(missing_docs)] -#![doc(primitive = "f32")] +#![allow(unsigned_negation)] use prelude::v1::*; diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs index 41c0fcb9797..4f2f59659ac 100644 --- a/src/libstd/num/f64.rs +++ b/src/libstd/num/f64.rs @@ -8,11 +8,12 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for 64-bits floats (`f64` type) +//! The 64-bit floating point type. +//! +//! *[See also the `f64` primitive type](../primitive.f64.html).* #![stable(feature = "rust1", since = "1.0.0")] #![allow(missing_docs)] -#![doc(primitive = "f64")] use prelude::v1::*; diff --git a/src/libstd/num/i16.rs b/src/libstd/num/i16.rs index 498f19b9b83..eb53e0821f2 100644 --- a/src/libstd/num/i16.rs +++ b/src/libstd/num/i16.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for signed 16-bits integers (`i16` type) +//! The 16-bit signed integer type. +//! +//! *[See also the `i16` primitive type](../primitive.i16.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i16")] pub use core::i16::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/i32.rs b/src/libstd/num/i32.rs index aea1e92117b..3c9eedf38c7 100644 --- a/src/libstd/num/i32.rs +++ b/src/libstd/num/i32.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for signed 32-bits integers (`i32` type) +//! The 32-bit signed integer type. +//! +//! *[See also the `i32` primitive type](../primitive.i32.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i32")] pub use core::i32::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/i64.rs b/src/libstd/num/i64.rs index 43794345fe7..2df7478a820 100644 --- a/src/libstd/num/i64.rs +++ b/src/libstd/num/i64.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for signed 64-bits integers (`i64` type) +//! The 64-bit signed integer type. +//! +//! *[See also the `i64` primitive type](../primitive.i64.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i64")] pub use core::i64::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/i8.rs b/src/libstd/num/i8.rs index 1b03bf6f4f0..4e4bee8a791 100644 --- a/src/libstd/num/i8.rs +++ b/src/libstd/num/i8.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for signed 8-bits integers (`i8` type) +//! The 8-bit signed integer type. +//! +//! *[See also the `i8` primitive type](../primitive.i8.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "i8")] pub use core::i8::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/isize.rs b/src/libstd/num/isize.rs index aa89f858f6f..d46b6b80d0d 100644 --- a/src/libstd/num/isize.rs +++ b/src/libstd/num/isize.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for pointer-sized signed integers (`isize` type) +//! The pointer-sized signed integer type. +//! +//! *[See also the `isize` primitive type](../primitive.isize.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "isize")] pub use core::isize::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/u16.rs b/src/libstd/num/u16.rs index 3fda77fb69c..893618aeffa 100644 --- a/src/libstd/num/u16.rs +++ b/src/libstd/num/u16.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for unsigned 16-bits integers (`u16` type) +//! The 16-bit unsigned integer type. +//! +//! *[See also the `u16` primitive type](../primitive.u16.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u16")] pub use core::u16::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/u32.rs b/src/libstd/num/u32.rs index 8610f0c0147..2da25519696 100644 --- a/src/libstd/num/u32.rs +++ b/src/libstd/num/u32.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for unsigned 32-bits integers (`u32` type) +//! The 32-bit unsigned integer type. +//! +//! *[See also the `u32` primitive type](../primitive.u32.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u32")] pub use core::u32::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/u64.rs b/src/libstd/num/u64.rs index 3587b069656..26a8b537394 100644 --- a/src/libstd/num/u64.rs +++ b/src/libstd/num/u64.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for unsigned 64-bits integer (`u64` type) +//! The 64-bit unsigned integer type. +//! +//! *[See also the `u64` primitive type](../primitive.u64.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u64")] pub use core::u64::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/u8.rs b/src/libstd/num/u8.rs index 6a285e8299c..385754b93a0 100644 --- a/src/libstd/num/u8.rs +++ b/src/libstd/num/u8.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for unsigned 8-bits integers (`u8` type) +//! The 8-bit unsigned integer type. +//! +//! *[See also the `u8` primitive type](../primitive.u8.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "u8")] pub use core::u8::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/num/usize.rs b/src/libstd/num/usize.rs index b54d8ae96c5..6960ba3b829 100644 --- a/src/libstd/num/usize.rs +++ b/src/libstd/num/usize.rs @@ -8,10 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Operations and constants for pointer-sized unsigned integers (`usize` type) +//! The pointer-sized unsigned integer type. +//! +//! *[See also the `usize` primitive type](../primitive.usize.html).* #![stable(feature = "rust1", since = "1.0.0")] -#![doc(primitive = "usize")] pub use core::usize::{BITS, BYTES, MIN, MAX}; diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs new file mode 100644 index 00000000000..066b2b576da --- /dev/null +++ b/src/libstd/primitive_docs.rs @@ -0,0 +1,420 @@ +// Copyright 2015 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or +// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license +// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +#[doc(primitive = "bool")] +// +/// The boolean type. +/// +mod prim_bool { } + +#[doc(primitive = "char")] +// +/// A Unicode scalar value. +/// +/// A `char` represents a +/// *[Unicode scalar +/// value](http://www.unicode.org/glossary/#unicode_scalar_value)*, as it can +/// contain any Unicode code point except high-surrogate and low-surrogate code +/// points. +/// +/// As such, only values in the ranges \[0x0,0xD7FF\] and \[0xE000,0x10FFFF\] +/// (inclusive) are allowed. A `char` can always be safely cast to a `u32`; +/// however the converse is not always true due to the above range limits +/// and, as such, should be performed via the `from_u32` function. +/// +/// *[See also the `std::char` module](char/index.html).* +/// +mod prim_char { } + +#[doc(primitive = "unit")] +// +/// The `()` type, sometimes called "unit" or "nil". +/// +/// The `()` type has exactly one value `()`, and is used when there +/// is no other meaningful value that could be returned. `()` is most +/// commonly seen implicitly: functions without a `-> ...` implicitly +/// have return type `()`, that is, these are equivalent: +/// +/// ```rust +/// fn long() -> () {} +/// +/// fn short() {} +/// ``` +/// +/// The semicolon `;` can be used to discard the result of an +/// expression at the end of a block, making the expression (and thus +/// the block) evaluate to `()`. For example, +/// +/// ```rust +/// fn returns_i64() -> i64 { +/// 1i64 +/// } +/// fn returns_unit() { +/// 1i64; +/// } +/// +/// let is_i64 = { +/// returns_i64() +/// }; +/// let is_unit = { +/// returns_i64(); +/// }; +/// ``` +/// +mod prim_unit { } + +#[doc(primitive = "pointer")] +// +/// Raw, unsafe pointers, `*const T`, and `*mut T`. +/// +/// Working with raw pointers in Rust is uncommon, +/// typically limited to a few patterns. +/// +/// Use the `null` function to create null pointers, and the `is_null` method +/// of the `*const T` type to check for null. The `*const T` type also defines +/// the `offset` method, for pointer math. +/// +/// # Common ways to create raw pointers +/// +/// ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`). +/// +/// ``` +/// let my_num: i32 = 10; +/// let my_num_ptr: *const i32 = &my_num; +/// let mut my_speed: i32 = 88; +/// let my_speed_ptr: *mut i32 = &mut my_speed; +/// ``` +/// +/// To get a pointer to a boxed value, dereference the box: +/// +/// ``` +/// let my_num: Box<i32> = Box::new(10); +/// let my_num_ptr: *const i32 = &*my_num; +/// let mut my_speed: Box<i32> = Box::new(88); +/// let my_speed_ptr: *mut i32 = &mut *my_speed; +/// ``` +/// +/// This does not take ownership of the original allocation +/// and requires no resource management later, +/// but you must not use the pointer after its lifetime. +/// +/// ## 2. Consume a box (`Box<T>`). +/// +/// The `into_raw` function consumes a box and returns +/// the raw pointer. It doesn't destroy `T` or deallocate any memory. +/// +/// ``` +/// # #![feature(box_raw)] +/// let my_speed: Box<i32> = Box::new(88); +/// let my_speed: *mut i32 = Box::into_raw(my_speed); +/// +/// // By taking ownership of the original `Box<T>` though +/// // we are obligated to put it together later to be destroyed. +/// unsafe { +/// drop(Box::from_raw(my_speed)); +/// } +/// ``` +/// +/// Note that here the call to `drop` is for clarity - it indicates +/// that we are done with the given value and it should be destroyed. +/// +/// ## 3. Get it from C. +/// +/// ``` +/// # #![feature(libc)] +/// extern crate libc; +/// +/// use std::mem; +/// +/// fn main() { +/// unsafe { +/// let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>() as libc::size_t) as *mut i32; +/// if my_num.is_null() { +/// panic!("failed to allocate memory"); +/// } +/// libc::free(my_num as *mut libc::c_void); +/// } +/// } +/// ``` +/// +/// Usually you wouldn't literally use `malloc` and `free` from Rust, +/// but C APIs hand out a lot of pointers generally, so are a common source +/// of raw pointers in Rust. +/// +/// *[See also the `std::ptr` module](ptr/index.html).* +/// +mod prim_pointer { } + +#[doc(primitive = "array")] +// +/// A fixed-size array, denoted `[T; N]`, for the element type, `T`, and +/// the non-negative compile time constant size, `N`. +/// +/// Arrays values are created either with an explicit expression that lists +/// each element: `[x, y, z]` or a repeat expression: `[x; N]`. The repeat +/// expression requires that the element type is `Copy`. +/// +/// The type `[T; N]` is `Copy` if `T: Copy`. +/// +/// Arrays of sizes from 0 to 32 (inclusive) implement the following traits +/// if the element type allows it: +/// +/// - `Clone` +/// - `Debug` +/// - `IntoIterator` (implemented for `&[T; N]` and `&mut [T; N]`) +/// - `PartialEq`, `PartialOrd`, `Ord`, `Eq` +/// - `Hash` +/// - `AsRef`, `AsMut` +/// +/// Arrays dereference to [slices (`[T]`)][slice], so their methods can be called +/// on arrays. +/// +/// [slice]: primitive.slice.html +/// +/// Rust does not currently support generics over the size of an array type. +/// +/// # Examples +/// +/// ``` +/// let mut array: [i32; 3] = [0; 3]; +/// +/// array[1] = 1; +/// array[2] = 2; +/// +/// assert_eq!([1, 2], &array[1..]); +/// +/// // This loop prints: 0 1 2 +/// for x in &array { +/// print!("{} ", x); +/// } +/// +/// ``` +/// +mod prim_array { } + +#[doc(primitive = "slice")] +// +/// A dynamically-sized view into a contiguous sequence, `[T]`. +/// +/// Slices are a view into a block of memory represented as a pointer and a +/// length. +/// +/// ``` +/// // slicing a Vec +/// let vec = vec![1, 2, 3]; +/// let int_slice = &vec[..]; +/// // coercing an array to a slice +/// let str_slice: &[&str] = &["one", "two", "three"]; +/// ``` +/// +/// Slices are either mutable or shared. The shared slice type is `&[T]`, +/// while the mutable slice type is `&mut [T]`, where `T` represents the element +/// type. For example, you can mutate the block of memory that a mutable slice +/// points to: +/// +/// ``` +/// let x = &mut [1, 2, 3]; +/// x[1] = 7; +/// assert_eq!(x, &[1, 7, 3]); +/// ``` +/// +/// *[See also the `std::slice` module](slice/index.html).* +/// +mod prim_slice { } + +#[doc(primitive = "str")] +// +/// Unicode string slices. +/// +/// Rust's `str` type is one of the core primitive types of the language. `&str` +/// is the borrowed string type. This type of string can only be created from +/// other strings, unless it is a `&'static str` (see below). It is not possible +/// to move out of borrowed strings because they are owned elsewhere. +/// +/// # Examples +/// +/// Here's some code that uses a `&str`: +/// +/// ``` +/// let s = "Hello, world."; +/// ``` +/// +/// This `&str` is a `&'static str`, which is the type of string literals. +/// They're `'static` because literals are available for the entire lifetime of +/// the program. +/// +/// You can get a non-`'static` `&str` by taking a slice of a `String`: +/// +/// ``` +/// let some_string = "Hello, world.".to_string(); +/// let s = &some_string; +/// ``` +/// +/// # Representation +/// +/// Rust's string type, `str`, is a sequence of Unicode scalar values encoded as +/// a stream of UTF-8 bytes. All [strings](../../reference.html#literals) are +/// guaranteed to be validly encoded UTF-8 sequences. Additionally, strings are +/// not null-terminated and can thus contain null bytes. +/// +/// The actual representation of `str`s have direct mappings to slices: `&str` +/// is the same as `&[u8]`. +/// +/// *[See also the `std::str` module](str/index.html).* +/// +mod prim_str { } + +#[doc(primitive = "tuple")] +// +/// A finite heterogeneous sequence, `(T, U, ..)`. +/// +/// To access the _N_-th element of a tuple one can use `N` itself +/// as a field of the tuple. +/// +/// Indexing starts from zero, so `0` returns first value, `1` +/// returns second value, and so on. In general, a tuple with _S_ +/// elements provides aforementioned fields from `0` to `S-1`. +/// +/// If every type inside a tuple implements one of the following +/// traits, then a tuple itself also implements it. +/// +/// * `Clone` +/// * `PartialEq` +/// * `Eq` +/// * `PartialOrd` +/// * `Ord` +/// * `Debug` +/// * `Default` +/// * `Hash` +/// +/// # Examples +/// +/// Accessing elements of a tuple at specified indices: +/// +/// ``` +/// let x = ("colorless", "green", "ideas", "sleep", "furiously"); +/// assert_eq!(x.3, "sleep"); +/// +/// let v = (3, 3); +/// let u = (1, -5); +/// assert_eq!(v.0 * u.0 + v.1 * u.1, -12); +/// ``` +/// +/// Using traits implemented for tuples: +/// +/// ``` +/// let a = (1, 2); +/// let b = (3, 4); +/// assert!(a != b); +/// +/// let c = b.clone(); +/// assert!(b == c); +/// +/// let d : (u32, f32) = Default::default(); +/// assert_eq!(d, (0, 0.0f32)); +/// ``` +/// +mod prim_tuple { } + +#[doc(primitive = "f32")] +/// The 32-bit floating point type. +/// +/// *[See also the `std::f32` module](f32/index.html).* +/// +mod prim_f32 { } + +#[doc(primitive = "f64")] +// +/// The 64-bit floating point type. +/// +/// *[See also the `std::f64` module](f64/index.html).* +/// +mod prim_f64 { } + +#[doc(primitive = "i8")] +// +/// The 8-bit signed integer type. +/// +/// *[See also the `std::i8` module](i8/index.html).* +/// +mod prim_i8 { } + +#[doc(primitive = "i16")] +// +/// The 16-bit signed integer type. +/// +/// *[See also the `std::i16` module](i16/index.html).* +/// +mod prim_i16 { } + +#[doc(primitive = "i32")] +// +/// The 32-bit signed integer type. +/// +/// *[See also the `std::i32` module](i32/index.html).* +/// +mod prim_i32 { } + +#[doc(primitive = "i64")] +// +/// The 64-bit signed integer type. +/// +/// *[See also the `std::i64` module](i64/index.html).* +/// +mod prim_i64 { } + +#[doc(primitive = "u8")] +// +/// The 8-bit unsigned integer type. +/// +/// *[See also the `std::u8` module](u8/index.html).* +/// +mod prim_u8 { } + +#[doc(primitive = "u16")] +// +/// The 16-bit unsigned integer type. +/// +/// *[See also the `std::u16` module](u16/index.html).* +/// +mod prim_u16 { } + +#[doc(primitive = "u32")] +// +/// The 32-bit unsigned integer type. +/// +/// *[See also the `std::u32` module](u32/index.html).* +/// +mod prim_u32 { } + +#[doc(primitive = "u64")] +// +/// The 64-bit unsigned integer type. +/// +/// *[See also the `std::u64` module](u64/index.html).* +/// +mod prim_u64 { } + +#[doc(primitive = "isize")] +// +/// The pointer-sized signed integer type. +/// +/// *[See also the `std::isize` module](isize/index.html).* +/// +mod prim_isize { } + +#[doc(primitive = "usize")] +// +/// The pointer-sized signed integer type. +/// +/// *[See also the `std::usize` module](usize/index.html).* +/// +mod prim_usize { } + diff --git a/src/libstd/tuple.rs b/src/libstd/tuple.rs deleted file mode 100644 index 08aa979cf63..00000000000 --- a/src/libstd/tuple.rs +++ /dev/null @@ -1,60 +0,0 @@ -// Copyright 2012 The Rust Project Developers. See the COPYRIGHT -// file at the top-level directory of this distribution and at -// http://rust-lang.org/COPYRIGHT. -// -// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or -// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license -// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your -// option. This file may not be copied, modified, or distributed -// except according to those terms. - -//! Operations on tuples -//! -//! To access the _N_-th element of a tuple one can use `N` itself -//! as a field of the tuple. -//! -//! Indexing starts from zero, so `0` returns first value, `1` -//! returns second value, and so on. In general, a tuple with _S_ -//! elements provides aforementioned fields from `0` to `S-1`. -//! -//! If every type inside a tuple implements one of the following -//! traits, then a tuple itself also implements it. -//! -//! * `Clone` -//! * `PartialEq` -//! * `Eq` -//! * `PartialOrd` -//! * `Ord` -//! * `Debug` -//! * `Default` -//! * `Hash` -//! -//! # Examples -//! -//! Accessing elements of a tuple at specified indices: -//! -//! ``` -//! let x = ("colorless", "green", "ideas", "sleep", "furiously"); -//! assert_eq!(x.3, "sleep"); -//! -//! let v = (3, 3); -//! let u = (1, -5); -//! assert_eq!(v.0 * u.0 + v.1 * u.1, -12); -//! ``` -//! -//! Using traits implemented for tuples: -//! -//! ``` -//! let a = (1, 2); -//! let b = (3, 4); -//! assert!(a != b); -//! -//! let c = b.clone(); -//! assert!(b == c); -//! -//! let d : (u32, f32) = Default::default(); -//! assert_eq!(d, (0, 0.0f32)); -//! ``` - -#![doc(primitive = "tuple")] -#![stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/unit.rs b/src/libstd/unit.rs deleted file mode 100644 index 2c3ddcd9d49..00000000000 --- a/src/libstd/unit.rs +++ /dev/null @@ -1,45 +0,0 @@ -// Copyright 2014 The Rust Project Developers. See the COPYRIGHT -// file at the top-level directory of this distribution and at -// http://rust-lang.org/COPYRIGHT. -// -// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or -// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license -// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your -// option. This file may not be copied, modified, or distributed -// except according to those terms. - -#![doc(primitive = "unit")] -#![stable(feature = "rust1", since = "1.0.0")] - -//! The `()` type, sometimes called "unit" or "nil". -//! -//! The `()` type has exactly one value `()`, and is used when there -//! is no other meaningful value that could be returned. `()` is most -//! commonly seen implicitly: functions without a `-> ...` implicitly -//! have return type `()`, that is, these are equivalent: -//! -//! ```rust -//! fn long() -> () {} -//! -//! fn short() {} -//! ``` -//! -//! The semicolon `;` can be used to discard the result of an -//! expression at the end of a block, making the expression (and thus -//! the block) evaluate to `()`. For example, -//! -//! ```rust -//! fn returns_i64() -> i64 { -//! 1i64 -//! } -//! fn returns_unit() { -//! 1i64; -//! } -//! -//! let is_i64 = { -//! returns_i64() -//! }; -//! let is_unit = { -//! returns_i64(); -//! }; -//! ``` |