diff --git a/RELEASES.md b/RELEASES.md index a747d04696821..e6f18f9f7ba55 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -54,7 +54,7 @@ Diagnostics Most common editors supporting Rust have been updated to work with it. It was previously described [on the Rust blog] (https://blog.rust-lang.org/2016/08/10/Shape-of-errors-to-come.html). -* [In error descriptions, references are now described in plain english, +* [In error descriptions, references are now described in plain English, instead of as "&-ptr"] (https://github.com/rust-lang/rust/pull/35611) * [In error type descriptions, unknown numeric types are named `{integer}` or @@ -148,7 +148,7 @@ Libraries (https://github.com/rust-lang/rust/pull/34946) * [`hash_map::Entry`, `hash_map::VacantEntry` and `hash_map::OccupiedEntry` implement `Debug`] - (https://github.com/rust-lang/rust/pull/34946) + (https://github.com/rust-lang/rust/pull/34937) * [`btree_map::Entry`, `btree_map::VacantEntry` and `btree_map::OccupiedEntry` implement `Debug`] (https://github.com/rust-lang/rust/pull/34885) @@ -885,7 +885,7 @@ Cargo Performance ----------- -* [The time complexity of comparing variables for equivalence during type +* [The time complexity of comparing variables for equivalence during type unification is reduced from _O_(_n_!) to _O_(_n_)][1.9tu]. This leads to major compilation time improvement in some scenarios. * [`ToString` is specialized for `str`, giving it the same performance diff --git a/src/doc/book/references-and-borrowing.md b/src/doc/book/references-and-borrowing.md index 2ec3a00c0df51..d845ad6feb001 100644 --- a/src/doc/book/references-and-borrowing.md +++ b/src/doc/book/references-and-borrowing.md @@ -86,7 +86,7 @@ fn main() { return v.iter().fold(0, |a, &b| a + b); } // Borrow two vectors and sum them. - // This kind of borrowing does not allow mutation to the borrowed. + // This kind of borrowing does not allow mutation through the borrowed reference. fn foo(v1: &Vec, v2: &Vec) -> i32 { // do stuff with v1 and v2 let s1 = sum_vec(v1); diff --git a/src/doc/reference.md b/src/doc/reference.md index b72c3743a69ce..20970ab7a3512 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -3959,6 +3959,16 @@ the top-level type for the implementation of the called method. If no such metho found, `.deref()` is called and the compiler continues to search for the method implementation in the returned type `U`. +## The `Send` trait + +The `Send` trait indicates that a value of this type is safe to send from one +thread to another. + +## The 'Sync' trait + +The 'Sync' trait indicates that a value of this type is safe to share between +multiple threads. + # Memory model A Rust program's memory consists of a static set of *items* and a *heap*. diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs index bc9b6e805efc9..28f4dda140883 100644 --- a/src/liballoc/boxed.rs +++ b/src/liballoc/boxed.rs @@ -244,12 +244,14 @@ impl Box { /// the destructor of `T` and free the allocated memory. Since the /// way `Box` allocates and releases memory is unspecified, the /// only valid pointer to pass to this function is the one taken - /// from another `Box` via the `Box::into_raw` function. + /// from another `Box` via the [`Box::into_raw`] function. /// /// This function is unsafe because improper use may lead to /// memory problems. For example, a double-free may occur if the /// function is called twice on the same raw pointer. /// + /// [`Box::into_raw`]: struct.Box.html#method.into_raw + /// /// # Examples /// /// ``` @@ -269,12 +271,14 @@ impl Box { /// memory previously managed by the `Box`. In particular, the /// caller should properly destroy `T` and release the memory. The /// proper way to do so is to convert the raw pointer back into a - /// `Box` with the `Box::from_raw` function. + /// `Box` with the [`Box::from_raw`] function. /// /// Note: this is an associated function, which means that you have /// to call it as `Box::into_raw(b)` instead of `b.into_raw()`. This /// is so that there is no conflict with a method on the inner type. /// + /// [`Box::from_raw`]: struct.Box.html#method.from_raw + /// /// # Examples /// /// ``` diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index 54dc7ec06da16..6b705ca039fd8 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -168,7 +168,7 @@ impl [T] { core_slice::SliceExt::len(self) } - /// Returns true if the slice has a length of 0 + /// Returns true if the slice has a length of 0. /// /// # Example /// @@ -402,7 +402,7 @@ impl [T] { core_slice::SliceExt::get_unchecked_mut(self, index) } - /// Returns an raw pointer to the slice's buffer + /// Returns an raw pointer to the slice's buffer. /// /// The caller must ensure that the slice outlives the pointer this /// function returns, or else it will end up pointing to garbage. @@ -468,7 +468,7 @@ impl [T] { /// /// # Examples /// - /// ```rust + /// ``` /// let mut v = ["a", "b", "c", "d"]; /// v.swap(1, 3); /// assert!(v == ["a", "d", "c", "b"]); @@ -483,7 +483,7 @@ impl [T] { /// /// # Example /// - /// ```rust + /// ``` /// let mut v = [1, 2, 3]; /// v.reverse(); /// assert!(v == [3, 2, 1]); @@ -567,9 +567,9 @@ impl [T] { } /// Returns an iterator over `size` elements of the slice at a - /// time. The chunks are slices and do not overlap. If `size` does not divide the - /// length of the slice, then the last chunk will not have length - /// `size`. + /// time. The chunks are slices and do not overlap. If `size` does + /// not divide the length of the slice, then the last chunk will + /// not have length `size`. /// /// # Panics /// @@ -656,7 +656,7 @@ impl [T] { /// /// # Examples /// - /// ```rust + /// ``` /// let mut v = [1, 2, 3, 4, 5, 6]; /// /// // scoped to restrict the lifetime of the borrows @@ -754,7 +754,7 @@ impl [T] { } /// Returns an iterator over subslices separated by elements that match - /// `pred`, limited to returning at most `n` items. The matched element is + /// `pred`, limited to returning at most `n` items. The matched element is /// not contained in the subslices. /// /// The last element returned, if any, will contain the remainder of the @@ -781,7 +781,7 @@ impl [T] { } /// Returns an iterator over subslices separated by elements that match - /// `pred`, limited to returning at most `n` items. The matched element is + /// `pred`, limited to returning at most `n` items. The matched element is /// not contained in the subslices. /// /// The last element returned, if any, will contain the remainder of the @@ -835,7 +835,7 @@ impl [T] { /// Returns an iterator over subslices separated by elements that match /// `pred` limited to returning at most `n` items. This starts at the end of - /// the slice and works backwards. The matched element is not contained in + /// the slice and works backwards. The matched element is not contained in /// the subslices. /// /// The last element returned, if any, will contain the remainder of the @@ -922,9 +922,9 @@ impl [T] { /// /// Looks up a series of four elements. The first is found, with a /// uniquely determined position; the second and third are not - /// found; the fourth could match any position in `[1,4]`. + /// found; the fourth could match any position in `[1, 4]`. /// - /// ```rust + /// ``` /// let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]; /// /// assert_eq!(s.binary_search(&13), Ok(9)); @@ -956,9 +956,9 @@ impl [T] { /// /// Looks up a series of four elements. The first is found, with a /// uniquely determined position; the second and third are not - /// found; the fourth could match any position in `[1,4]`. + /// found; the fourth could match any position in `[1, 4]`. /// - /// ```rust + /// ``` /// let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]; /// /// let seek = 13; @@ -982,21 +982,23 @@ impl [T] { /// Binary search a sorted slice with a key extraction function. /// /// Assumes that the slice is sorted by the key, for instance with - /// `sort_by_key` using the same key extraction function. + /// [`sort_by_key`] using the same key extraction function. /// /// If a matching value is found then returns `Ok`, containing the /// index for the matched element; if no match is found then `Err` /// is returned, containing the index where a matching element could /// be inserted while maintaining sorted order. /// + /// [`sort_by_key`]: #method.sort_by_key + /// /// # Examples /// /// Looks up a series of four elements in a slice of pairs sorted by /// their second elements. The first is found, with a uniquely /// determined position; the second and third are not found; the - /// fourth could match any position in `[1,4]`. + /// fourth could match any position in `[1, 4]`. /// - /// ```rust + /// ``` /// let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1), /// (1, 2), (2, 3), (4, 5), (5, 8), (3, 13), /// (1, 21), (2, 34), (4, 55)]; @@ -1023,7 +1025,7 @@ impl [T] { /// /// # Examples /// - /// ```rust + /// ``` /// let mut v = [-5, 4, 1, -3, 2]; /// /// v.sort(); @@ -1045,7 +1047,7 @@ impl [T] { /// /// # Examples /// - /// ```rust + /// ``` /// let mut v = [-5i32, 4, 1, -3, 2]; /// /// v.sort_by_key(|k| k.abs()); @@ -1067,7 +1069,7 @@ impl [T] { /// /// # Examples /// - /// ```rust + /// ``` /// let mut v = [5, 4, 1, 3, 2]; /// v.sort_by(|a, b| a.cmp(b)); /// assert!(v == [1, 2, 3, 4, 5]); @@ -1094,7 +1096,7 @@ impl [T] { /// /// # Example /// - /// ```rust + /// ``` /// let mut dst = [0, 0, 0]; /// let src = [1, 2, 3]; /// @@ -1116,7 +1118,7 @@ impl [T] { /// /// # Example /// - /// ```rust + /// ``` /// let mut dst = [0, 0, 0]; /// let src = [1, 2, 3]; /// diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs index 6a6b450e51863..96efe1a03e351 100644 --- a/src/libcollections/str.rs +++ b/src/libcollections/str.rs @@ -697,7 +697,7 @@ impl str { /// /// Basic usage: /// - /// ```rust + /// ``` /// let bananas = "bananas"; /// /// assert!(bananas.ends_with("anas")); @@ -900,7 +900,7 @@ impl str { /// /// It does _not_ give you: /// - /// ```rust,ignore + /// ```,ignore /// assert_eq!(d, &["a", "b", "c"]); /// ``` /// diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index e4930ae357208..119828ea43c61 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -21,7 +21,7 @@ //! //! There are multiple ways to create a new `String` from a string literal: //! -//! ```rust +//! ``` //! let s = "Hello".to_string(); //! //! let s = String::from("world"); @@ -31,7 +31,7 @@ //! You can create a new `String` from an existing one by concatenating with //! `+`: //! -//! ```rust +//! ``` //! let s = "Hello".to_string(); //! //! let message = s + " world!"; @@ -40,7 +40,7 @@ //! If you have a vector of valid UTF-8 bytes, you can make a `String` out of //! it. You can do the reverse too. //! -//! ```rust +//! ``` //! let sparkle_heart = vec![240, 159, 146, 150]; //! //! // We know these bytes are valid, so we'll use `unwrap()`. diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index e868a542d55fd..ed6eb62c9677e 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -1769,7 +1769,7 @@ impl IntoIter { /// /// # Examples /// - /// ```rust + /// ``` /// # #![feature(vec_into_iter_as_slice)] /// let vec = vec!['a', 'b', 'c']; /// let mut into_iter = vec.into_iter(); @@ -1788,7 +1788,7 @@ impl IntoIter { /// /// # Examples /// - /// ```rust + /// ``` /// # #![feature(vec_into_iter_as_slice)] /// let vec = vec!['a', 'b', 'c']; /// let mut into_iter = vec.into_iter(); diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs index f990a27e52b31..036633fe89dc6 100644 --- a/src/libcore/cmp.rs +++ b/src/libcore/cmp.rs @@ -10,10 +10,13 @@ //! Functionality for ordering and comparison. //! -//! This module defines both `PartialOrd` and `PartialEq` traits which are used +//! This module defines both [`PartialOrd`] and [`PartialEq`] traits which are used //! by the compiler to implement comparison operators. Rust programs may -//! implement `PartialOrd` to overload the `<`, `<=`, `>`, and `>=` operators, -//! and may implement `PartialEq` to overload the `==` and `!=` operators. +//! implement [`PartialOrd`] to overload the `<`, `<=`, `>`, and `>=` operators, +//! and may implement [`PartialEq`] to overload the `==` and `!=` operators. +//! +//! [`PartialOrd`]: trait.PartialOrd.html +//! [`PartialEq`]: trait.PartialEq.html //! //! # Examples //! diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs index 5d7f41556c25f..a9f53d3abb8b9 100644 --- a/src/libcore/fmt/mod.rs +++ b/src/libcore/fmt/mod.rs @@ -794,7 +794,7 @@ pub trait UpperExp { /// assert_eq!(output, "Hello world!"); /// ``` /// -/// Please note that using [`write!`][write_macro] might be preferrable. Example: +/// Please note that using [`write!`] might be preferrable. Example: /// /// ``` /// use std::fmt::Write; @@ -805,7 +805,7 @@ pub trait UpperExp { /// assert_eq!(output, "Hello world!"); /// ``` /// -/// [write_macro]: ../../std/macro.write!.html +/// [`write!`]: ../../std/macro.write.html #[stable(feature = "rust1", since = "1.0.0")] pub fn write(output: &mut Write, args: Arguments) -> Result { let mut formatter = Formatter { diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 85a52da332db5..72e951a7c347c 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -14,7 +14,7 @@ //! //! Some of these traits are imported by the prelude, so they are available in //! every Rust program. Only operators backed by traits can be overloaded. For -//! example, the addition operator (`+`) can be overloaded through the `Add` +//! example, the addition operator (`+`) can be overloaded through the [`Add`] //! trait, but since the assignment operator (`=`) has no backing trait, there //! is no way of overloading its semantics. Additionally, this module does not //! provide any mechanism to create new operators. If traitless overloading or @@ -30,17 +30,18 @@ //! contexts involving built-in types, this is usually not a problem. //! However, using these operators in generic code, requires some //! attention if values have to be reused as opposed to letting the operators -//! consume them. One option is to occasionally use `clone()`. +//! consume them. One option is to occasionally use [`clone()`]. //! Another option is to rely on the types involved providing additional //! operator implementations for references. For example, for a user-defined //! type `T` which is supposed to support addition, it is probably a good -//! idea to have both `T` and `&T` implement the traits `Add` and `Add<&T>` -//! so that generic code can be written without unnecessary cloning. +//! idea to have both `T` and `&T` implement the traits [`Add`][`Add`] and +//! [`Add<&T>`][`Add`] so that generic code can be written without unnecessary +//! cloning. //! //! # Examples //! -//! This example creates a `Point` struct that implements `Add` and `Sub`, and -//! then demonstrates adding and subtracting two `Point`s. +//! This example creates a `Point` struct that implements [`Add`] and [`Sub`], +//! and then demonstrates adding and subtracting two `Point`s. //! //! ```rust //! use std::ops::{Add, Sub}; @@ -75,18 +76,14 @@ //! See the documentation for each trait for an example implementation. //! //! The [`Fn`], [`FnMut`], and [`FnOnce`] traits are implemented by types that can be -//! invoked like functions. Note that `Fn` takes `&self`, `FnMut` takes `&mut -//! self` and `FnOnce` takes `self`. These correspond to the three kinds of +//! invoked like functions. Note that [`Fn`] takes `&self`, [`FnMut`] takes `&mut +//! self` and [`FnOnce`] takes `self`. These correspond to the three kinds of //! methods that can be invoked on an instance: call-by-reference, //! call-by-mutable-reference, and call-by-value. The most common use of these //! traits is to act as bounds to higher-level functions that take functions or //! closures as arguments. //! -//! [`Fn`]: trait.Fn.html -//! [`FnMut`]: trait.FnMut.html -//! [`FnOnce`]: trait.FnOnce.html -//! -//! Taking a `Fn` as a parameter: +//! Taking a [`Fn`] as a parameter: //! //! ```rust //! fn call_with_one(func: F) -> usize @@ -99,7 +96,7 @@ //! assert_eq!(call_with_one(double), 2); //! ``` //! -//! Taking a `FnMut` as a parameter: +//! Taking a [`FnMut`] as a parameter: //! //! ```rust //! fn do_twice(mut func: F) @@ -118,7 +115,7 @@ //! assert_eq!(x, 5); //! ``` //! -//! Taking a `FnOnce` as a parameter: +//! Taking a [`FnOnce`] as a parameter: //! //! ```rust //! fn consume_with_relish(func: F) @@ -140,6 +137,13 @@ //! //! // `consume_and_return_x` can no longer be invoked at this point //! ``` +//! +//! [`Fn`]: trait.Fn.html +//! [`FnMut`]: trait.FnMut.html +//! [`FnOnce`]: trait.FnOnce.html +//! [`Add`]: trait.Add.html +//! [`Sub`]: trait.Sub.html +//! [`clone()`]: ../clone/trait.Clone.html#tymethod.clone #![stable(feature = "rust1", since = "1.0.0")] @@ -1873,7 +1877,7 @@ macro_rules! shr_assign_impl_all { shr_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize } /// The `Index` trait is used to specify the functionality of indexing operations -/// like `arr[idx]` when used in an immutable context. +/// like `container[index]` when used in an immutable context. /// /// # Examples /// @@ -1924,50 +1928,50 @@ pub trait Index { #[stable(feature = "rust1", since = "1.0.0")] type Output: ?Sized; - /// The method for the indexing (`Foo[Bar]`) operation + /// The method for the indexing (`container[index]`) operation #[stable(feature = "rust1", since = "1.0.0")] fn index(&self, index: Idx) -> &Self::Output; } /// The `IndexMut` trait is used to specify the functionality of indexing -/// operations like `arr[idx]`, when used in a mutable context. +/// operations like `container[index]`, when used in a mutable context. /// /// # Examples /// -/// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up -/// calling `index_mut`, and therefore, `main` prints `Indexing!`. +/// A trivial implementation of `IndexMut` for a type `Foo`. When `&mut Foo[2]` +/// happens, it ends up calling `index_mut`, and therefore, `main` prints +/// `Mutable indexing with 2!`. /// /// ``` /// use std::ops::{Index, IndexMut}; /// /// #[derive(Copy, Clone)] /// struct Foo; -/// struct Bar; /// -/// impl Index for Foo { +/// impl Index for Foo { /// type Output = Foo; /// -/// fn index<'a>(&'a self, _index: Bar) -> &'a Foo { +/// fn index(&self, _index: usize) -> &Foo { /// self /// } /// } /// -/// impl IndexMut for Foo { -/// fn index_mut<'a>(&'a mut self, _index: Bar) -> &'a mut Foo { -/// println!("Indexing!"); +/// impl IndexMut for Foo { +/// fn index_mut(&mut self, index: usize) -> &mut Foo { +/// println!("Mutable indexing with {}!", index); /// self /// } /// } /// /// fn main() { -/// &mut Foo[Bar]; +/// &mut Foo[2]; /// } /// ``` #[lang = "index_mut"] #[rustc_on_unimplemented = "the type `{Self}` cannot be mutably indexed by `{Idx}`"] #[stable(feature = "rust1", since = "1.0.0")] pub trait IndexMut: Index { - /// The method for the indexing (`Foo[Bar]`) operation + /// The method for the mutable indexing (`container[index]`) operation #[stable(feature = "rust1", since = "1.0.0")] fn index_mut(&mut self, index: Idx) -> &mut Self::Output; } diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 0de02cbf19c9f..e308a2d8e0375 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -1264,15 +1264,13 @@ pub trait BufRead: Read { #[stable(feature = "rust1", since = "1.0.0")] fn consume(&mut self, amt: usize); - /// Read all bytes into `buf` until the delimiter `byte` is reached. + /// Read all bytes into `buf` until the delimiter `byte` or EOF is reached. /// /// This function will read bytes from the underlying stream until the /// delimiter or EOF is found. Once found, all bytes up to, and including, /// the delimiter (if found) will be appended to `buf`. /// - /// If this reader is currently at EOF then this function will not modify - /// `buf` and will return `Ok(n)` where `n` is the number of bytes which - /// were read. + /// If successful, this function will return the total number of bytes read. /// /// # Errors /// @@ -1315,9 +1313,7 @@ pub trait BufRead: Read { /// up to, and including, the delimiter (if found) will be appended to /// `buf`. /// - /// If this reader is currently at EOF then this function will not modify - /// `buf` and will return `Ok(n)` where `n` is the number of bytes which - /// were read. + /// If successful, this function will return the total number of bytes read. /// /// # Errors /// diff --git a/src/libstd/process.rs b/src/libstd/process.rs index f0c4443070074..674b00095370e 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -8,7 +8,25 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Working with processes. +//! A module for working with processes. +//! +//! # Examples +//! +//! Basic usage where we try to execute the `cat` shell command: +//! +//! ```should_panic +//! use std::process::Command; +//! +//! let mut child = Command::new("/bin/cat") +//! .arg("file.txt") +//! .spawn() +//! .expect("failed to execute child"); +//! +//! let ecode = child.wait() +//! .expect("failed to wait on child"); +//! +//! assert!(ecode.success()); +//! ``` #![stable(feature = "process", since = "1.0.0")] diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index d8e021bb04ff9..a634c8f77a45c 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -151,7 +151,7 @@ //! //! [`Cell`]: ../cell/struct.Cell.html //! [`RefCell`]: ../cell/struct.RefCell.html -//! [`thread_local!`]: ../macro.thread_local!.html +//! [`thread_local!`]: ../macro.thread_local.html //! [`with`]: struct.LocalKey.html#method.with #![stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/time/mod.rs b/src/libstd/time/mod.rs index 154f603c84f16..6854f1e14fa13 100644 --- a/src/libstd/time/mod.rs +++ b/src/libstd/time/mod.rs @@ -118,7 +118,7 @@ pub struct Instant(time::Instant); pub struct SystemTime(time::SystemTime); /// An error returned from the `duration_since` method on `SystemTime`, -/// used to learn about why how far in the opposite direction a timestamp lies. +/// used to learn how far in the opposite direction a system time lies. #[derive(Clone, Debug)] #[stable(feature = "time2", since = "1.8.0")] pub struct SystemTimeError(Duration);