From 97a1b6a055d69cf21faa9773133725bdfddc5196 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 12 Mar 2017 14:13:35 -0400 Subject: Update usages of 'OSX' (and other old names) to 'macOS'. As of last year with version 'Sierra', the Mac operating system is now called 'macOS'. --- src/libstd/thread/local.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/local.rs b/src/libstd/thread/local.rs index 66f09a7069c..e2b22b1d89f 100644 --- a/src/libstd/thread/local.rs +++ b/src/libstd/thread/local.rs @@ -74,7 +74,7 @@ use mem; /// destroyed, but not all platforms have this guard. Those platforms that do /// not guard typically have a synthetic limit after which point no more /// destructors are run. -/// 3. On OSX, initializing TLS during destruction of other TLS slots can +/// 3. On macOS, initializing TLS during destruction of other TLS slots can /// sometimes cancel *all* destructors for the current thread, whether or not /// the slots have already had their destructors run or not. #[stable(feature = "rust1", since = "1.0.0")] @@ -524,9 +524,9 @@ mod tests { } // Note that this test will deadlock if TLS destructors aren't run (this - // requires the destructor to be run to pass the test). OSX has a known bug + // requires the destructor to be run to pass the test). macOS has a known bug // where dtors-in-dtors may cancel other destructors, so we just ignore this - // test on OSX. + // test on macOS. #[test] #[cfg_attr(target_os = "macos", ignore)] fn dtors_in_dtors_in_dtors() { -- cgit 1.4.1-3-g733a5 From 1545f4e2a323eb869b13f36bd05cc91ff21d5161 Mon Sep 17 00:00:00 2001 From: Sean Gillespie Date: Mon, 13 Mar 2017 18:42:23 -0700 Subject: std: remove a workaround for privacy limitations that isn't necessary anymore --- src/libstd/rt.rs | 4 ++-- src/libstd/sys_common/thread_info.rs | 7 +------ src/libstd/thread/mod.rs | 7 +------ 3 files changed, 4 insertions(+), 14 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/rt.rs b/src/libstd/rt.rs index 78d5aa597ba..6c791cd336d 100644 --- a/src/libstd/rt.rs +++ b/src/libstd/rt.rs @@ -34,7 +34,7 @@ fn lang_start(main: *const u8, argc: isize, argv: *const *const u8) -> isize { use panic; use sys; use sys_common; - use sys_common::thread_info::{self, NewThread}; + use sys_common::thread_info; use thread::Thread; sys::init(); @@ -47,7 +47,7 @@ fn lang_start(main: *const u8, argc: isize, argv: *const *const u8) -> isize { // created. Note that this isn't necessary in general for new threads, // but we just do this to name the main thread and to give it correct // info about the stack bounds. - let thread: Thread = NewThread::new(Some("main".to_owned())); + let thread = Thread::new(Some("main".to_owned())); thread_info::set(main_guard, thread); // Store our args if necessary in a squirreled away location diff --git a/src/libstd/sys_common/thread_info.rs b/src/libstd/sys_common/thread_info.rs index 95d8b6cc951..5ed48ee4558 100644 --- a/src/libstd/sys_common/thread_info.rs +++ b/src/libstd/sys_common/thread_info.rs @@ -31,7 +31,7 @@ impl ThreadInfo { if c.borrow().is_none() { *c.borrow_mut() = Some(ThreadInfo { stack_guard: None, - thread: NewThread::new(None), + thread: Thread::new(None), }) } Some(f(c.borrow_mut().as_mut().unwrap())) @@ -54,8 +54,3 @@ pub fn set(stack_guard: Option, thread: Thread) { thread: thread, })); } - -// a hack to get around privacy restrictions; implemented by `std::thread` -pub trait NewThread { - fn new(name: Option) -> Self; -} diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2bc066d3fea..fa4cc276ee5 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -745,7 +745,7 @@ pub struct Thread { impl Thread { // Used only internally to construct a thread object without spawning - fn new(name: Option) -> Thread { + pub(crate) fn new(name: Option) -> Thread { let cname = name.map(|n| { CString::new(n).expect("thread name may not contain interior null bytes") }); @@ -858,11 +858,6 @@ impl fmt::Debug for Thread { } } -// a hack to get around privacy restrictions -impl thread_info::NewThread for Thread { - fn new(name: Option) -> Thread { Thread::new(name) } -} - //////////////////////////////////////////////////////////////////////////////// // JoinHandle //////////////////////////////////////////////////////////////////////////////// -- cgit 1.4.1-3-g733a5 From e7b0f2badf7c3393f1b36339b121054d05353442 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 12 Mar 2017 14:04:52 -0400 Subject: Remove function invokation parens from documentation links. This was never established as a convention we should follow in the 'More API Documentation Conventions' RFC: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md --- src/doc/book/src/ffi.md | 8 +-- src/doc/book/src/guessing-game.md | 2 +- src/liballoc/rc.rs | 4 +- src/libcollections/binary_heap.rs | 4 +- src/libcollections/slice.rs | 22 +++---- src/libcollections/str.rs | 68 ++++++++++----------- src/libcollections/string.rs | 94 ++++++++++++++--------------- src/libcollections/vec.rs | 42 ++++++------- src/libcore/char.rs | 20 +++---- src/libcore/clone.rs | 4 +- src/libcore/convert.rs | 8 +-- src/libcore/hash/mod.rs | 4 +- src/libcore/iter/iterator.rs | 64 ++++++++++---------- src/libcore/iter/mod.rs | 120 +++++++++++++++++++------------------- src/libcore/iter/sources.rs | 22 +++---- src/libcore/iter/traits.rs | 50 ++++++++-------- src/libcore/macros.rs | 4 +- src/libcore/marker.rs | 4 +- src/libcore/mem.rs | 2 +- src/libcore/num/mod.rs | 10 ++-- src/libcore/ops.rs | 14 ++--- src/libcore/str/mod.rs | 70 +++++++++++----------- src/libstd/fs.rs | 8 +-- src/libstd/io/error.rs | 4 +- src/libstd/io/mod.rs | 92 ++++++++++++++--------------- src/libstd/io/stdio.rs | 4 +- src/libstd/io/util.rs | 6 +- src/libstd/lib.rs | 4 +- src/libstd/net/tcp.rs | 18 +++--- src/libstd/net/udp.rs | 20 +++---- src/libstd/panicking.rs | 8 +-- src/libstd/path.rs | 32 +++++----- src/libstd/prelude/mod.rs | 8 +-- src/libstd/primitive_docs.rs | 6 +- src/libstd/sync/barrier.rs | 4 +- src/libstd/sync/condvar.rs | 18 +++--- src/libstd/sync/mpsc/mod.rs | 12 ++-- src/libstd/sync/mutex.rs | 6 +- src/libstd/sync/rwlock.rs | 12 ++-- src/libstd/sys/unix/ext/net.rs | 34 +++++------ src/libstd/thread/mod.rs | 32 +++++----- src/libstd_unicode/char.rs | 14 ++--- 42 files changed, 491 insertions(+), 491 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/doc/book/src/ffi.md b/src/doc/book/src/ffi.md index e9e2dab73ef..3dd9aa3885b 100644 --- a/src/doc/book/src/ffi.md +++ b/src/doc/book/src/ffi.md @@ -687,7 +687,7 @@ attribute turns off Rust's name mangling, so that it is easier to link to. It’s important to be mindful of `panic!`s when working with FFI. A `panic!` across an FFI boundary is undefined behavior. If you’re writing code that may -panic, you should run it in a closure with [`catch_unwind()`]: +panic, you should run it in a closure with [`catch_unwind`]: ```rust use std::panic::catch_unwind; @@ -706,11 +706,11 @@ pub extern fn oh_no() -> i32 { fn main() {} ``` -Please note that [`catch_unwind()`] will only catch unwinding panics, not -those who abort the process. See the documentation of [`catch_unwind()`] +Please note that [`catch_unwind`] will only catch unwinding panics, not +those who abort the process. See the documentation of [`catch_unwind`] for more information. -[`catch_unwind()`]: ../std/panic/fn.catch_unwind.html +[`catch_unwind`]: ../std/panic/fn.catch_unwind.html # Representing opaque structs diff --git a/src/doc/book/src/guessing-game.md b/src/doc/book/src/guessing-game.md index 4d81438b11d..bbb43b4a9ef 100644 --- a/src/doc/book/src/guessing-game.md +++ b/src/doc/book/src/guessing-game.md @@ -217,7 +217,7 @@ The next part will use this handle to get input from the user: .read_line(&mut guess) ``` -Here, we call the [`read_line()`][read_line] method on our handle. +Here, we call the [`read_line`][read_line] method on our handle. [Methods][method] are like associated functions, but are only available on a particular instance of a type, rather than the type itself. We’re also passing one argument to `read_line()`: `&mut guess`. diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index 6108a06634b..eb449b26606 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -13,7 +13,7 @@ //! Single-threaded reference-counting pointers. //! //! The type [`Rc`][`Rc`] provides shared ownership of a value of type `T`, -//! allocated in the heap. Invoking [`clone()`][clone] on [`Rc`] produces a new +//! allocated in the heap. Invoking [`clone`][clone] on [`Rc`] produces a new //! pointer to the same value in the heap. When the last [`Rc`] pointer to a //! given value is destroyed, the pointed-to value is also destroyed. //! @@ -30,7 +30,7 @@ //! threads. If you need multi-threaded, atomic reference counting, use //! [`sync::Arc`][arc]. //! -//! The [`downgrade()`][downgrade] method can be used to create a non-owning +//! The [`downgrade`][downgrade] method can be used to create a non-owning //! [`Weak`] pointer. A [`Weak`] pointer can be [`upgrade`][upgrade]d //! to an [`Rc`], but this will return [`None`] if the value has //! already been dropped. diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index a5a2f70492d..519117ff9e5 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -218,10 +218,10 @@ pub struct BinaryHeap { data: Vec, } -/// A container object that represents the result of the [`peek_mut()`] method +/// A container object that represents the result of the [`peek_mut`] method /// on `BinaryHeap`. See its documentation for details. /// -/// [`peek_mut()`]: struct.BinaryHeap.html#method.peek_mut +/// [`peek_mut`]: struct.BinaryHeap.html#method.peek_mut #[stable(feature = "binary_heap_peek_mut", since = "1.12.0")] pub struct PeekMut<'a, T: 'a + Ord> { heap: &'a mut BinaryHeap, diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index 2ea953df873..11fc1d553f2 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -73,10 +73,10 @@ //! the element type of the slice is `i32`, the element type of the iterator is //! `&mut i32`. //! -//! * [`.iter()`] and [`.iter_mut()`] are the explicit methods to return the default +//! * [`.iter`] and [`.iter_mut`] are the explicit methods to return the default //! iterators. -//! * Further methods that return iterators are [`.split()`], [`.splitn()`], -//! [`.chunks()`], [`.windows()`] and more. +//! * Further methods that return iterators are [`.split`], [`.splitn`], +//! [`.chunks`], [`.windows`] and more. //! //! *[See also the slice primitive type](../../std/primitive.slice.html).* //! @@ -85,12 +85,12 @@ //! [`Ord`]: ../../std/cmp/trait.Ord.html //! [`Iter`]: struct.Iter.html //! [`Hash`]: ../../std/hash/trait.Hash.html -//! [`.iter()`]: ../../std/primitive.slice.html#method.iter -//! [`.iter_mut()`]: ../../std/primitive.slice.html#method.iter_mut -//! [`.split()`]: ../../std/primitive.slice.html#method.split -//! [`.splitn()`]: ../../std/primitive.slice.html#method.splitn -//! [`.chunks()`]: ../../std/primitive.slice.html#method.chunks -//! [`.windows()`]: ../../std/primitive.slice.html#method.windows +//! [`.iter`]: ../../std/primitive.slice.html#method.iter +//! [`.iter_mut`]: ../../std/primitive.slice.html#method.iter_mut +//! [`.split`]: ../../std/primitive.slice.html#method.split +//! [`.splitn`]: ../../std/primitive.slice.html#method.splitn +//! [`.chunks`]: ../../std/primitive.slice.html#method.chunks +//! [`.windows`]: ../../std/primitive.slice.html#method.windows #![stable(feature = "rust1", since = "1.0.0")] // Many of the usings in this module are only used in the test configuration. @@ -368,9 +368,9 @@ impl [T] { } /// Returns a mutable reference to an element or subslice depending on the - /// type of index (see [`get()`]) or `None` if the index is out of bounds. + /// type of index (see [`get`]) or `None` if the index is out of bounds. /// - /// [`get()`]: #method.get + /// [`get`]: #method.get /// /// # Examples /// diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs index e27c4577344..90e54a383d6 100644 --- a/src/libcollections/str.rs +++ b/src/libcollections/str.rs @@ -298,9 +298,9 @@ impl str { /// excluding `end`. /// /// To get a mutable string slice instead, see the - /// [`slice_mut_unchecked()`] method. + /// [`slice_mut_unchecked`] method. /// - /// [`slice_mut_unchecked()`]: #method.slice_mut_unchecked + /// [`slice_mut_unchecked`]: #method.slice_mut_unchecked /// /// # Safety /// @@ -341,9 +341,9 @@ impl str { /// excluding `end`. /// /// To get an immutable string slice instead, see the - /// [`slice_unchecked()`] method. + /// [`slice_unchecked`] method. /// - /// [`slice_unchecked()`]: #method.slice_unchecked + /// [`slice_unchecked`]: #method.slice_unchecked /// /// # Safety /// @@ -367,10 +367,10 @@ impl str { /// The two slices returned go from the start of the string slice to `mid`, /// and from `mid` to the end of the string slice. /// - /// To get mutable string slices instead, see the [`split_at_mut()`] + /// To get mutable string slices instead, see the [`split_at_mut`] /// method. /// - /// [`split_at_mut()`]: #method.split_at_mut + /// [`split_at_mut`]: #method.split_at_mut /// /// # Panics /// @@ -403,9 +403,9 @@ impl str { /// The two slices returned go from the start of the string slice to `mid`, /// and from `mid` to the end of the string slice. /// - /// To get immutable string slices instead, see the [`split_at()`] method. + /// To get immutable string slices instead, see the [`split_at`] method. /// - /// [`split_at()`]: #method.split_at + /// [`split_at`]: #method.split_at /// /// # Panics /// @@ -824,10 +824,10 @@ impl str { /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html /// /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rsplit()`] method can be used. + /// from a forward search, the [`rsplit`] method can be used. /// /// [`char`]: primitive.char.html - /// [`rsplit()`]: #method.rsplit + /// [`rsplit`]: #method.rsplit /// /// # Examples /// @@ -912,9 +912,9 @@ impl str { /// assert_eq!(d, &["a", "b", "c"]); /// ``` /// - /// Use [`split_whitespace()`] for this behavior. + /// Use [`split_whitespace`] for this behavior. /// - /// [`split_whitespace()`]: #method.split_whitespace + /// [`split_whitespace`]: #method.split_whitespace #[stable(feature = "rust1", since = "1.0.0")] pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> { core_str::StrExt::split(self, pat) @@ -936,9 +936,9 @@ impl str { /// /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html /// - /// For iterating from the front, the [`split()`] method can be used. + /// For iterating from the front, the [`split`] method can be used. /// - /// [`split()`]: #method.split + /// [`split`]: #method.split /// /// # Examples /// @@ -977,10 +977,10 @@ impl str { /// The pattern can be a `&str`, [`char`], or a closure that determines the /// split. /// - /// Equivalent to [`split()`], except that the trailing substring + /// Equivalent to [`split`], except that the trailing substring /// is skipped if empty. /// - /// [`split()`]: #method.split + /// [`split`]: #method.split /// /// This method can be used for string data that is _terminated_, /// rather than _separated_ by a pattern. @@ -995,9 +995,9 @@ impl str { /// [`char`]: primitive.char.html /// /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rsplit_terminator()`] method can be used. + /// from a forward search, the [`rsplit_terminator`] method can be used. /// - /// [`rsplit_terminator()`]: #method.rsplit_terminator + /// [`rsplit_terminator`]: #method.rsplit_terminator /// /// # Examples /// @@ -1025,10 +1025,10 @@ impl str { /// /// [`char`]: primitive.char.html /// - /// Equivalent to [`split()`], except that the trailing substring is + /// Equivalent to [`split`], except that the trailing substring is /// skipped if empty. /// - /// [`split()`]: #method.split + /// [`split`]: #method.split /// /// This method can be used for string data that is _terminated_, /// rather than _separated_ by a pattern. @@ -1039,10 +1039,10 @@ impl str { /// reverse search, and it will be double ended if a forward/reverse /// search yields the same elements. /// - /// For iterating from the front, the [`split_terminator()`] method can be + /// For iterating from the front, the [`split_terminator`] method can be /// used. /// - /// [`split_terminator()`]: #method.split_terminator + /// [`split_terminator`]: #method.split_terminator /// /// # Examples /// @@ -1076,10 +1076,10 @@ impl str { /// The returned iterator will not be double ended, because it is /// not efficient to support. /// - /// If the pattern allows a reverse search, the [`rsplitn()`] method can be + /// If the pattern allows a reverse search, the [`rsplitn`] method can be /// used. /// - /// [`rsplitn()`]: #method.rsplitn + /// [`rsplitn`]: #method.rsplitn /// /// # Examples /// @@ -1127,9 +1127,9 @@ impl str { /// The returned iterator will not be double ended, because it is not /// efficient to support. /// - /// For splitting from the front, the [`splitn()`] method can be used. + /// For splitting from the front, the [`splitn`] method can be used. /// - /// [`splitn()`]: #method.splitn + /// [`splitn`]: #method.splitn /// /// # Examples /// @@ -1177,9 +1177,9 @@ impl str { /// [`char`]: primitive.char.html /// /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rmatches()`] method can be used. + /// from a forward search, the [`rmatches`] method can be used. /// - /// [`rmatches()`]: #method.rmatches + /// [`rmatches`]: #method.rmatches /// /// # Examples /// @@ -1213,9 +1213,9 @@ impl str { /// /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html /// - /// For iterating from the front, the [`matches()`] method can be used. + /// For iterating from the front, the [`matches`] method can be used. /// - /// [`matches()`]: #method.matches + /// [`matches`]: #method.matches /// /// # Examples /// @@ -1255,9 +1255,9 @@ impl str { /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html /// /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rmatch_indices()`] method can be used. + /// from a forward search, the [`rmatch_indices`] method can be used. /// - /// [`rmatch_indices()`]: #method.rmatch_indices + /// [`rmatch_indices`]: #method.rmatch_indices /// /// # Examples /// @@ -1297,9 +1297,9 @@ impl str { /// /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html /// - /// For iterating from the front, the [`match_indices()`] method can be used. + /// For iterating from the front, the [`match_indices`] method can be used. /// - /// [`match_indices()`]: #method.match_indices + /// [`match_indices`]: #method.match_indices /// /// # Examples /// diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 43323676ab4..e8e3a25a8f4 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -89,8 +89,8 @@ use boxed::Box; /// let hello = String::from("Hello, world!"); /// ``` /// -/// You can append a [`char`] to a `String` with the [`push()`] method, and -/// append a [`&str`] with the [`push_str()`] method: +/// You can append a [`char`] to a `String` with the [`push`] method, and +/// append a [`&str`] with the [`push_str`] method: /// /// ``` /// let mut hello = String::from("Hello, "); @@ -100,11 +100,11 @@ use boxed::Box; /// ``` /// /// [`char`]: ../../std/primitive.char.html -/// [`push()`]: #method.push -/// [`push_str()`]: #method.push_str +/// [`push`]: #method.push +/// [`push_str`]: #method.push_str /// /// If you have a vector of UTF-8 bytes, you can create a `String` from it with -/// the [`from_utf8()`] method: +/// the [`from_utf8`] method: /// /// ``` /// // some bytes, in a vector @@ -116,7 +116,7 @@ use boxed::Box; /// assert_eq!("💖", sparkle_heart); /// ``` /// -/// [`from_utf8()`]: #method.from_utf8 +/// [`from_utf8`]: #method.from_utf8 /// /// # UTF-8 /// @@ -136,11 +136,11 @@ use boxed::Box; /// Indexing is intended to be a constant-time operation, but UTF-8 encoding /// does not allow us to do this. Furthermore, it's not clear what sort of /// thing the index should return: a byte, a codepoint, or a grapheme cluster. -/// The [`bytes()`] and [`chars()`] methods return iterators over the first +/// The [`bytes`] and [`chars`] methods return iterators over the first /// two, respectively. /// -/// [`bytes()`]: #method.bytes -/// [`chars()`]: #method.chars +/// [`bytes`]: #method.bytes +/// [`chars`]: #method.chars /// /// # Deref /// @@ -174,7 +174,7 @@ use boxed::Box; /// /// This buffer is always stored on the heap. /// -/// You can look at these with the [`as_ptr()`], [`len()`], and [`capacity()`] +/// You can look at these with the [`as_ptr`], [`len`], and [`capacity`] /// methods: /// /// ``` @@ -200,9 +200,9 @@ use boxed::Box; /// assert_eq!(String::from("Once upon a time..."), s); /// ``` /// -/// [`as_ptr()`]: #method.as_ptr -/// [`len()`]: #method.len -/// [`capacity()`]: #method.capacity +/// [`as_ptr`]: #method.as_ptr +/// [`len`]: #method.len +/// [`capacity`]: #method.capacity /// /// If a `String` has enough capacity, adding elements to it will not /// re-allocate. For example, consider this program: @@ -231,7 +231,7 @@ use boxed::Box; /// /// At first, we have no memory allocated at all, but as we append to the /// string, it increases its capacity appropriately. If we instead use the -/// [`with_capacity()`] method to allocate the correct capacity initially: +/// [`with_capacity`] method to allocate the correct capacity initially: /// /// ``` /// let mut s = String::with_capacity(25); @@ -244,7 +244,7 @@ use boxed::Box; /// } /// ``` /// -/// [`with_capacity()`]: #method.with_capacity +/// [`with_capacity`]: #method.with_capacity /// /// We end up with a different output: /// @@ -266,25 +266,25 @@ pub struct String { /// A possible error value when converting a `String` from a UTF-8 byte vector. /// -/// This type is the error type for the [`from_utf8()`] method on [`String`]. It +/// This type is the error type for the [`from_utf8`] method on [`String`]. It /// is designed in such a way to carefully avoid reallocations: the -/// [`into_bytes()`] method will give back the byte vector that was used in the +/// [`into_bytes`] method will give back the byte vector that was used in the /// conversion attempt. /// -/// [`from_utf8()`]: struct.String.html#method.from_utf8 +/// [`from_utf8`]: struct.String.html#method.from_utf8 /// [`String`]: struct.String.html -/// [`into_bytes()`]: struct.FromUtf8Error.html#method.into_bytes +/// [`into_bytes`]: struct.FromUtf8Error.html#method.into_bytes /// /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's /// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error` -/// through the [`utf8_error()`] method. +/// through the [`utf8_error`] method. /// /// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html /// [`std::str`]: ../../std/str/index.html /// [`u8`]: ../../std/primitive.u8.html /// [`&str`]: ../../std/primitive.str.html -/// [`utf8_error()`]: #method.utf8_error +/// [`utf8_error`]: #method.utf8_error /// /// # Examples /// @@ -308,9 +308,9 @@ pub struct FromUtf8Error { /// A possible error value when converting a `String` from a UTF-16 byte slice. /// -/// This type is the error type for the [`from_utf16()`] method on [`String`]. +/// This type is the error type for the [`from_utf16`] method on [`String`]. /// -/// [`from_utf16()`]: struct.String.html#method.from_utf16 +/// [`from_utf16`]: struct.String.html#method.from_utf16 /// [`String`]: struct.String.html /// /// # Examples @@ -335,10 +335,10 @@ impl String { /// buffer. While that means that this initial operation is very /// inexpensive, but may cause excessive allocation later, when you add /// data. If you have an idea of how much data the `String` will hold, - /// consider the [`with_capacity()`] method to prevent excessive + /// consider the [`with_capacity`] method to prevent excessive /// re-allocation. /// - /// [`with_capacity()`]: #method.with_capacity + /// [`with_capacity`]: #method.with_capacity /// /// # Examples /// @@ -356,18 +356,18 @@ impl String { /// Creates a new empty `String` with a particular capacity. /// /// `String`s have an internal buffer to hold their data. The capacity is - /// the length of that buffer, and can be queried with the [`capacity()`] + /// the length of that buffer, and can be queried with the [`capacity`] /// method. This method creates an empty `String`, but one with an initial /// buffer that can hold `capacity` bytes. This is useful when you may be /// appending a bunch of data to the `String`, reducing the number of /// reallocations it needs to do. /// - /// [`capacity()`]: #method.capacity + /// [`capacity`]: #method.capacity /// /// If the given capacity is `0`, no allocation will occur, and this method - /// is identical to the [`new()`] method. + /// is identical to the [`new`] method. /// - /// [`new()`]: #method.new + /// [`new`]: #method.new /// /// # Examples /// @@ -420,18 +420,18 @@ impl String { /// /// If you are sure that the byte slice is valid UTF-8, and you don't want /// to incur the overhead of the validity check, there is an unsafe version - /// of this function, [`from_utf8_unchecked()`], which has the same behavior + /// of this function, [`from_utf8_unchecked`], which has the same behavior /// but skips the check. /// - /// [`from_utf8_unchecked()`]: struct.String.html#method.from_utf8_unchecked + /// [`from_utf8_unchecked`]: struct.String.html#method.from_utf8_unchecked /// /// This method will take care to not copy the vector, for efficiency's /// sake. /// /// If you need a `&str` instead of a `String`, consider - /// [`str::from_utf8()`]. + /// [`str::from_utf8`]. /// - /// [`str::from_utf8()`]: ../../std/str/fn.from_utf8.html + /// [`str::from_utf8`]: ../../std/str/fn.from_utf8.html /// /// The inverse of this method is [`as_bytes`]. /// @@ -497,10 +497,10 @@ impl String { /// /// If you are sure that the byte slice is valid UTF-8, and you don't want /// to incur the overhead of the conversion, there is an unsafe version - /// of this function, [`from_utf8_unchecked()`], which has the same behavior + /// of this function, [`from_utf8_unchecked`], which has the same behavior /// but skips the checks. /// - /// [`from_utf8_unchecked()`]: struct.String.html#method.from_utf8_unchecked + /// [`from_utf8_unchecked`]: struct.String.html#method.from_utf8_unchecked /// /// This function returns a [`Cow<'a, str>`]. If our byte slice is invalid /// UTF-8, then we need to insert the replacement characters, which will @@ -738,9 +738,9 @@ impl String { /// Converts a vector of bytes to a `String` without checking that the /// string contains valid UTF-8. /// - /// See the safe version, [`from_utf8()`], for more details. + /// See the safe version, [`from_utf8`], for more details. /// - /// [`from_utf8()`]: struct.String.html#method.from_utf8 + /// [`from_utf8`]: struct.String.html#method.from_utf8 /// /// # Safety /// @@ -845,10 +845,10 @@ impl String { /// The capacity may be increased by more than `additional` bytes if it /// chooses, to prevent frequent reallocations. /// - /// If you do not want this "at least" behavior, see the [`reserve_exact()`] + /// If you do not want this "at least" behavior, see the [`reserve_exact`] /// method. /// - /// [`reserve_exact()`]: #method.reserve_exact + /// [`reserve_exact`]: #method.reserve_exact /// /// # Panics /// @@ -892,10 +892,10 @@ impl String { /// Ensures that this `String`'s capacity is `additional` bytes /// larger than its length. /// - /// Consider using the [`reserve()`] method unless you absolutely know + /// Consider using the [`reserve`] method unless you absolutely know /// better than the allocator. /// - /// [`reserve()`]: #method.reserve + /// [`reserve`]: #method.reserve /// /// # Panics /// @@ -1699,9 +1699,9 @@ impl<'a> Add<&'a str> for String { /// Implements the `+=` operator for appending to a `String`. /// -/// This has the same behavior as the [`push_str()`] method. +/// This has the same behavior as the [`push_str`] method. /// -/// [`push_str()`]: struct.String.html#method.push_str +/// [`push_str`]: struct.String.html#method.push_str #[stable(feature = "stringaddassign", since = "1.12.0")] impl<'a> AddAssign<&'a str> for String { #[inline] @@ -1830,14 +1830,14 @@ impl ops::DerefMut for String { /// /// This `enum` is slightly awkward: it will never actually exist. This error is /// part of the type signature of the implementation of [`FromStr`] on -/// [`String`]. The return type of [`from_str()`], requires that an error be +/// [`String`]. The return type of [`from_str`], requires that an error be /// defined, but, given that a [`String`] can always be made into a new /// [`String`] without error, this type will never actually be returned. As /// such, it is only here to satisfy said signature, and is useless otherwise. /// /// [`FromStr`]: ../../std/str/trait.FromStr.html /// [`String`]: struct.String.html -/// [`from_str()`]: ../../std/str/trait.FromStr.html#tymethod.from_str +/// [`from_str`]: ../../std/str/trait.FromStr.html#tymethod.from_str #[stable(feature = "str_parse_error", since = "1.5.0")] #[derive(Copy)] pub enum ParseError {} @@ -2042,10 +2042,10 @@ impl fmt::Write for String { /// A draining iterator for `String`. /// -/// This struct is created by the [`drain()`] method on [`String`]. See its +/// This struct is created by the [`drain`] method on [`String`]. See its /// documentation for more. /// -/// [`drain()`]: struct.String.html#method.drain +/// [`drain`]: struct.String.html#method.drain /// [`String`]: struct.String.html #[stable(feature = "drain", since = "1.6.0")] pub struct Drain<'a> { diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index d38c9f6e1cf..76bc3fc3575 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -16,7 +16,7 @@ //! //! # Examples //! -//! You can explicitly create a [`Vec`] with [`new()`]: +//! You can explicitly create a [`Vec`] with [`new`]: //! //! ``` //! let v: Vec = Vec::new(); @@ -58,7 +58,7 @@ //! ``` //! //! [`Vec`]: ../../std/vec/struct.Vec.html -//! [`new()`]: ../../std/vec/struct.Vec.html#method.new +//! [`new`]: ../../std/vec/struct.Vec.html#method.new //! [`push`]: ../../std/vec/struct.Vec.html#method.push //! [`Index`]: ../../std/ops/trait.Index.html //! [`IndexMut`]: ../../std/ops/trait.IndexMut.html @@ -216,19 +216,19 @@ use Bound::{Excluded, Included, Unbounded}; /// The pointer will never be null, so this type is null-pointer-optimized. /// /// However, the pointer may not actually point to allocated memory. In particular, -/// if you construct a `Vec` with capacity 0 via [`Vec::new()`], [`vec![]`][`vec!`], -/// [`Vec::with_capacity(0)`][`Vec::with_capacity`], or by calling [`shrink_to_fit()`] +/// if you construct a `Vec` with capacity 0 via [`Vec::new`], [`vec![]`][`vec!`], +/// [`Vec::with_capacity(0)`][`Vec::with_capacity`], or by calling [`shrink_to_fit`] /// on an empty Vec, it will not allocate memory. Similarly, if you store zero-sized /// types inside a `Vec`, it will not allocate space for them. *Note that in this case -/// the `Vec` may not report a [`capacity()`] of 0*. `Vec` will allocate if and only -/// if [`mem::size_of::()`]` * capacity() > 0`. In general, `Vec`'s allocation +/// the `Vec` may not report a [`capacity`] of 0*. `Vec` will allocate if and only +/// if [`mem::size_of::`]` * capacity() > 0`. In general, `Vec`'s allocation /// details are subtle enough that it is strongly recommended that you only /// free memory allocated by a `Vec` by creating a new `Vec` and dropping it. /// /// If a `Vec` *has* allocated memory, then the memory it points to is on the heap /// (as defined by the allocator Rust is configured to use by default), and its -/// pointer points to [`len()`] initialized elements in order (what you would see -/// if you coerced it to a slice), followed by [`capacity()`]` - `[`len()`] +/// pointer points to [`len`] initialized elements in order (what you would see +/// if you coerced it to a slice), followed by [`capacity`]` - `[`len`] /// logically uninitialized elements. /// /// `Vec` will never perform a "small optimization" where elements are actually @@ -244,13 +244,13 @@ use Bound::{Excluded, Included, Unbounded}; /// /// `Vec` will never automatically shrink itself, even if completely empty. This /// ensures no unnecessary allocations or deallocations occur. Emptying a `Vec` -/// and then filling it back up to the same [`len()`] should incur no calls to +/// and then filling it back up to the same [`len`] should incur no calls to /// the allocator. If you wish to free up unused memory, use -/// [`shrink_to_fit`][`shrink_to_fit()`]. +/// [`shrink_to_fit`][`shrink_to_fit`]. /// /// [`push`] and [`insert`] will never (re)allocate if the reported capacity is /// sufficient. [`push`] and [`insert`] *will* (re)allocate if -/// [`len()`]` == `[`capacity()`]. That is, the reported capacity is completely +/// [`len`]` == `[`capacity`]. That is, the reported capacity is completely /// accurate, and can be relied on. It can even be used to manually free the memory /// allocated by a `Vec` if desired. Bulk insertion methods *may* reallocate, even /// when not necessary. @@ -262,7 +262,7 @@ use Bound::{Excluded, Included, Unbounded}; /// /// `vec![x; n]`, `vec![a, b, c, d]`, and /// [`Vec::with_capacity(n)`][`Vec::with_capacity`], will all produce a `Vec` -/// with exactly the requested capacity. If [`len()`]` == `[`capacity()`], +/// with exactly the requested capacity. If [`len`]` == `[`capacity`], /// (as is the case for the [`vec!`] macro), then a `Vec` can be converted to /// and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements. /// @@ -283,11 +283,11 @@ use Bound::{Excluded, Included, Unbounded}; /// [`String`]: ../../std/string/struct.String.html /// [`&str`]: ../../std/primitive.str.html /// [`Vec::with_capacity`]: ../../std/vec/struct.Vec.html#method.with_capacity -/// [`Vec::new()`]: ../../std/vec/struct.Vec.html#method.new -/// [`shrink_to_fit()`]: ../../std/vec/struct.Vec.html#method.shrink_to_fit -/// [`capacity()`]: ../../std/vec/struct.Vec.html#method.capacity -/// [`mem::size_of::()`]: ../../std/mem/fn.size_of.html -/// [`len()`]: ../../std/vec/struct.Vec.html#method.len +/// [`Vec::new`]: ../../std/vec/struct.Vec.html#method.new +/// [`shrink_to_fit`]: ../../std/vec/struct.Vec.html#method.shrink_to_fit +/// [`capacity`]: ../../std/vec/struct.Vec.html#method.capacity +/// [`mem::size_of::`]: ../../std/mem/fn.size_of.html +/// [`len`]: ../../std/vec/struct.Vec.html#method.len /// [`push`]: ../../std/vec/struct.Vec.html#method.push /// [`insert`]: ../../std/vec/struct.Vec.html#method.insert /// [`reserve`]: ../../std/vec/struct.Vec.html#method.reserve @@ -504,12 +504,12 @@ impl Vec { /// Converts the vector into [`Box<[T]>`][owned slice]. /// /// Note that this will drop any excess capacity. Calling this and - /// converting back to a vector with [`into_vec()`] is equivalent to calling - /// [`shrink_to_fit()`]. + /// converting back to a vector with [`into_vec`] is equivalent to calling + /// [`shrink_to_fit`]. /// /// [owned slice]: ../../std/boxed/struct.Box.html - /// [`into_vec()`]: ../../std/primitive.slice.html#method.into_vec - /// [`shrink_to_fit()`]: #method.shrink_to_fit + /// [`into_vec`]: ../../std/primitive.slice.html#method.into_vec + /// [`shrink_to_fit`]: #method.shrink_to_fit /// /// # Examples /// diff --git a/src/libcore/char.rs b/src/libcore/char.rs index 78764091cf0..a9282b5b02f 100644 --- a/src/libcore/char.rs +++ b/src/libcore/char.rs @@ -97,9 +97,9 @@ pub const MAX: char = '\u{10ffff}'; /// [`as`]: ../../book/casting-between-types.html#as /// /// For an unsafe version of this function which ignores these checks, see -/// [`from_u32_unchecked()`]. +/// [`from_u32_unchecked`]. /// -/// [`from_u32_unchecked()`]: fn.from_u32_unchecked.html +/// [`from_u32_unchecked`]: fn.from_u32_unchecked.html /// /// # Examples /// @@ -152,9 +152,9 @@ pub fn from_u32(i: u32) -> Option { /// /// This function is unsafe, as it may construct invalid `char` values. /// -/// For a safe version of this function, see the [`from_u32()`] function. +/// For a safe version of this function, see the [`from_u32`] function. /// -/// [`from_u32()`]: fn.from_u32.html +/// [`from_u32`]: fn.from_u32.html /// /// # Examples /// @@ -479,10 +479,10 @@ impl CharExt for char { /// Returns an iterator that yields the hexadecimal Unicode escape of a /// character, as `char`s. /// -/// This `struct` is created by the [`escape_unicode()`] method on [`char`]. See +/// This `struct` is created by the [`escape_unicode`] method on [`char`]. See /// its documentation for more. /// -/// [`escape_unicode()`]: ../../std/primitive.char.html#method.escape_unicode +/// [`escape_unicode`]: ../../std/primitive.char.html#method.escape_unicode /// [`char`]: ../../std/primitive.char.html #[derive(Clone, Debug)] #[stable(feature = "rust1", since = "1.0.0")] @@ -600,10 +600,10 @@ impl fmt::Display for EscapeUnicode { /// An iterator that yields the literal escape code of a `char`. /// -/// This `struct` is created by the [`escape_default()`] method on [`char`]. See +/// This `struct` is created by the [`escape_default`] method on [`char`]. See /// its documentation for more. /// -/// [`escape_default()`]: ../../std/primitive.char.html#method.escape_default +/// [`escape_default`]: ../../std/primitive.char.html#method.escape_default /// [`char`]: ../../std/primitive.char.html #[derive(Clone, Debug)] #[stable(feature = "rust1", since = "1.0.0")] @@ -713,10 +713,10 @@ impl fmt::Display for EscapeDefault { /// An iterator that yields the literal escape code of a `char`. /// -/// This `struct` is created by the [`escape_debug()`] method on [`char`]. See its +/// This `struct` is created by the [`escape_debug`] method on [`char`]. See its /// documentation for more. /// -/// [`escape_debug()`]: ../../std/primitive.char.html#method.escape_debug +/// [`escape_debug`]: ../../std/primitive.char.html#method.escape_debug /// [`char`]: ../../std/primitive.char.html #[unstable(feature = "char_escape_debug", issue = "35068")] #[derive(Clone, Debug)] diff --git a/src/libcore/clone.rs b/src/libcore/clone.rs index 8dbbc5928f4..97b9525da67 100644 --- a/src/libcore/clone.rs +++ b/src/libcore/clone.rs @@ -61,7 +61,7 @@ /// ## Derivable /// /// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d -/// implementation of [`clone()`] calls [`clone()`] on each field. +/// implementation of [`clone`] calls [`clone`] on each field. /// /// ## How can I implement `Clone`? /// @@ -75,7 +75,7 @@ /// `Clone` cannot be `derive`d, but can be implemented as: /// /// [`Copy`]: ../../std/marker/trait.Copy.html -/// [`clone()`]: trait.Clone.html#tymethod.clone +/// [`clone`]: trait.Clone.html#tymethod.clone /// /// ``` /// #[derive(Copy)] diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 4e170794c1d..70e285f202e 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -154,14 +154,14 @@ pub trait AsMut { /// # Generic Impls /// /// - [`From`][From]` for U` implies `Into for T` -/// - [`into()`] is reflexive, which means that `Into for T` is implemented +/// - [`into`] is reflexive, which means that `Into for T` is implemented /// /// [`TryInto`]: trait.TryInto.html /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html /// [`String`]: ../../std/string/struct.String.html /// [From]: trait.From.html -/// [`into()`]: trait.Into.html#tymethod.into +/// [`into`]: trait.Into.html#tymethod.into #[stable(feature = "rust1", since = "1.0.0")] pub trait Into: Sized { /// Performs the conversion. @@ -187,14 +187,14 @@ pub trait Into: Sized { /// # Generic impls /// /// - `From for U` implies [`Into`]` for T` -/// - [`from()`] is reflexive, which means that `From for T` is implemented +/// - [`from`] is reflexive, which means that `From for T` is implemented /// /// [`TryFrom`]: trait.TryFrom.html /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html /// [`String`]: ../../std/string/struct.String.html /// [`Into`]: trait.Into.html -/// [`from()`]: trait.From.html#tymethod.from +/// [`from`]: trait.From.html#tymethod.from #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. diff --git a/src/libcore/hash/mod.rs b/src/libcore/hash/mod.rs index f0d8d1a3219..aadeaac83d5 100644 --- a/src/libcore/hash/mod.rs +++ b/src/libcore/hash/mod.rs @@ -106,7 +106,7 @@ mod sip; /// /// This trait can be used with `#[derive]` if all fields implement `Hash`. /// When `derive`d, the resulting hash will be the combination of the values -/// from calling [`.hash()`] on each field. +/// from calling [`.hash`] on each field. /// /// ## How can I implement `Hash`? /// @@ -133,7 +133,7 @@ mod sip; /// [`Eq`]: ../../std/cmp/trait.Eq.html /// [`HashMap`]: ../../std/collections/struct.HashMap.html /// [`HashSet`]: ../../std/collections/struct.HashSet.html -/// [`.hash()`]: #tymethod.hash +/// [`.hash`]: #tymethod.hash #[stable(feature = "rust1", since = "1.0.0")] pub trait Hash { /// Feeds this value into the state given, updating the hasher as necessary. diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 0f47378aebb..1301c311c14 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -140,11 +140,11 @@ pub trait Iterator { /// Consumes the iterator, counting the number of iterations and returning it. /// - /// This method will evaluate the iterator until its [`next()`] returns + /// This method will evaluate the iterator until its [`next`] returns /// [`None`]. Once [`None`] is encountered, `count()` returns the number of - /// times it called [`next()`]. + /// times it called [`next`]. /// - /// [`next()`]: #tymethod.next + /// [`next`]: #tymethod.next /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Overflow Behavior @@ -323,7 +323,7 @@ pub trait Iterator { /// /// In other words, it zips two iterators together, into a single one. /// - /// When either iterator returns [`None`], all further calls to [`next()`] + /// When either iterator returns [`None`], all further calls to [`next`] /// will return [`None`]. /// /// # Examples @@ -364,7 +364,7 @@ pub trait Iterator { /// /// `zip()` is often used to zip an infinite iterator to a finite one. /// This works because the finite iterator will eventually return [`None`], - /// ending the zipper. Zipping with `(0..)` can look a lot like [`enumerate()`]: + /// ending the zipper. Zipping with `(0..)` can look a lot like [`enumerate`]: /// /// ``` /// let enumerate: Vec<_> = "foo".chars().enumerate().collect(); @@ -381,8 +381,8 @@ pub trait Iterator { /// assert_eq!((2, 'o'), zipper[2]); /// ``` /// - /// [`enumerate()`]: trait.Iterator.html#method.enumerate - /// [`next()`]: ../../std/iter/trait.Iterator.html#tymethod.next + /// [`enumerate`]: trait.Iterator.html#method.enumerate + /// [`next`]: ../../std/iter/trait.Iterator.html#tymethod.next /// [`None`]: ../../std/option/enum.Option.html#variant.None #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -524,11 +524,11 @@ pub trait Iterator { /// closure returns [`None`], it will try again, and call the closure on the /// next element, seeing if it will return [`Some`]. /// - /// Why `filter_map()` and not just [`filter()`].[`map()`]? The key is in this + /// Why `filter_map()` and not just [`filter()`].[`map`]? The key is in this /// part: /// - /// [`filter()`]: #method.filter - /// [`map()`]: #method.map + /// [`filter`]: #method.filter + /// [`map`]: #method.map /// /// > If the closure returns [`Some(element)`][`Some`], then that element is returned. /// @@ -550,7 +550,7 @@ pub trait Iterator { /// assert_eq!(iter.next(), None); /// ``` /// - /// Here's the same example, but with [`filter()`] and [`map()`]: + /// Here's the same example, but with [`filter`] and [`map`]: /// /// ``` /// let a = ["1", "2", "lol"]; @@ -585,7 +585,7 @@ pub trait Iterator { /// iterator. /// /// `enumerate()` keeps its count as a [`usize`]. If you want to count by a - /// different sized integer, the [`zip()`] function provides similar + /// different sized integer, the [`zip`] function provides similar /// functionality. /// /// # Overflow Behavior @@ -601,7 +601,7 @@ pub trait Iterator { /// /// [`usize::MAX`]: ../../std/usize/constant.MAX.html /// [`usize`]: ../../std/primitive.usize.html - /// [`zip()`]: #method.zip + /// [`zip`]: #method.zip /// /// # Examples /// @@ -624,16 +624,16 @@ pub trait Iterator { /// Creates an iterator which can use `peek` to look at the next element of /// the iterator without consuming it. /// - /// Adds a [`peek()`] method to an iterator. See its documentation for + /// Adds a [`peek`] method to an iterator. See its documentation for /// more information. /// - /// Note that the underlying iterator is still advanced when [`peek()`] is + /// Note that the underlying iterator is still advanced when [`peek`] is /// called for the first time: In order to retrieve the next element, - /// [`next()`] is called on the underlying iterator, hence any side effects of - /// the [`next()`] method will occur. + /// [`next`] is called on the underlying iterator, hence any side effects of + /// the [`next`] method will occur. /// - /// [`peek()`]: struct.Peekable.html#method.peek - /// [`next()`]: ../../std/iter/trait.Iterator.html#tymethod.next + /// [`peek`]: struct.Peekable.html#method.peek + /// [`next`]: ../../std/iter/trait.Iterator.html#tymethod.next /// /// # Examples /// @@ -666,9 +666,9 @@ pub trait Iterator { Peekable{iter: self, peeked: None} } - /// Creates an iterator that [`skip()`]s elements based on a predicate. + /// Creates an iterator that [`skip`]s elements based on a predicate. /// - /// [`skip()`]: #method.skip + /// [`skip`]: #method.skip /// /// `skip_while()` takes a closure as an argument. It will call this /// closure on each element of the iterator, and ignore elements @@ -863,10 +863,10 @@ pub trait Iterator { Take{iter: self, n: n} } - /// An iterator adaptor similar to [`fold()`] that holds internal state and + /// An iterator adaptor similar to [`fold`] that holds internal state and /// produces a new iterator. /// - /// [`fold()`]: #method.fold + /// [`fold`]: #method.fold /// /// `scan()` takes two arguments: an initial value which seeds the internal /// state, and a closure with two arguments, the first being a mutable @@ -910,16 +910,16 @@ pub trait Iterator { /// Creates an iterator that works like map, but flattens nested structure. /// - /// The [`map()`] adapter is very useful, but only when the closure + /// The [`map`] adapter is very useful, but only when the closure /// argument produces values. If it produces an iterator instead, there's /// an extra layer of indirection. `flat_map()` will remove this extra layer /// on its own. /// - /// Another way of thinking about `flat_map()`: [`map()`]'s closure returns + /// Another way of thinking about `flat_map()`: [`map`]'s closure returns /// one item for each element, and `flat_map()`'s closure returns an /// iterator for each element. /// - /// [`map()`]: #method.map + /// [`map`]: #method.map /// /// # Examples /// @@ -1106,7 +1106,7 @@ pub trait Iterator { /// library, used in a variety of contexts. /// /// The most basic pattern in which `collect()` is used is to turn one - /// collection into another. You take a collection, call [`iter()`] on it, + /// collection into another. You take a collection, call [`iter`] on it, /// do a bunch of transformations, and then `collect()` at the end. /// /// One of the keys to `collect()`'s power is that many things you might @@ -1211,7 +1211,7 @@ pub trait Iterator { /// assert_eq!(Ok(vec![1, 3]), result); /// ``` /// - /// [`iter()`]: ../../std/iter/trait.Iterator.html#tymethod.next + /// [`iter`]: ../../std/iter/trait.Iterator.html#tymethod.next /// [`String`]: ../../std/string/struct.String.html /// [`char`]: ../../std/primitive.char.html /// [`Result`]: ../../std/result/enum.Result.html @@ -1816,9 +1816,9 @@ pub trait Iterator { /// collections: one from the left elements of the pairs, and one /// from the right elements. /// - /// This function is, in some sense, the opposite of [`zip()`]. + /// This function is, in some sense, the opposite of [`zip`]. /// - /// [`zip()`]: #method.zip + /// [`zip`]: #method.zip /// /// # Examples /// @@ -1849,12 +1849,12 @@ pub trait Iterator { (ts, us) } - /// Creates an iterator which [`clone()`]s all of its elements. + /// Creates an iterator which [`clone`]s all of its elements. /// /// This is useful when you have an iterator over `&T`, but you need an /// iterator over `T`. /// - /// [`clone()`]: ../../std/clone/trait.Clone.html#tymethod.clone + /// [`clone`]: ../../std/clone/trait.Clone.html#tymethod.clone /// /// # Examples /// diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs index d9b8c5ea589..dcb3da4f839 100644 --- a/src/libcore/iter/mod.rs +++ b/src/libcore/iter/mod.rs @@ -48,15 +48,15 @@ //! } //! ``` //! -//! An iterator has a method, [`next()`], which when called, returns an -//! [`Option`]``. [`next()`] will return `Some(Item)` as long as there +//! An iterator has a method, [`next`], which when called, returns an +//! [`Option`]``. [`next`] will return `Some(Item)` as long as there //! are elements, and once they've all been exhausted, will return `None` to //! indicate that iteration is finished. Individual iterators may choose to -//! resume iteration, and so calling [`next()`] again may or may not eventually +//! resume iteration, and so calling [`next`] again may or may not eventually //! start returning `Some(Item)` again at some point. //! //! [`Iterator`]'s full definition includes a number of other methods as well, -//! but they are default methods, built on top of [`next()`], and so you get +//! but they are default methods, built on top of [`next`], and so you get //! them for free. //! //! Iterators are also composable, and it's common to chain them together to do @@ -64,7 +64,7 @@ //! below for more details. //! //! [`Iterator`]: trait.Iterator.html -//! [`next()`]: trait.Iterator.html#tymethod.next +//! [`next`]: trait.Iterator.html#tymethod.next //! [`Option`]: ../../std/option/enum.Option.html //! //! # The three forms of iteration @@ -168,13 +168,13 @@ //! produce an iterator. What gives? //! //! There's a trait in the standard library for converting something into an -//! iterator: [`IntoIterator`]. This trait has one method, [`into_iter()`], +//! iterator: [`IntoIterator`]. This trait has one method, [`into_iter`], //! which converts the thing implementing [`IntoIterator`] into an iterator. //! Let's take a look at that `for` loop again, and what the compiler converts //! it into: //! //! [`IntoIterator`]: trait.IntoIterator.html -//! [`into_iter()`]: trait.IntoIterator.html#tymethod.into_iter +//! [`into_iter`]: trait.IntoIterator.html#tymethod.into_iter //! //! ``` //! let values = vec![1, 2, 3, 4, 5]; @@ -202,7 +202,7 @@ //! ``` //! //! First, we call `into_iter()` on the value. Then, we match on the iterator -//! that returns, calling [`next()`] over and over until we see a `None`. At +//! that returns, calling [`next`] over and over until we see a `None`. At //! that point, we `break` out of the loop, and we're done iterating. //! //! There's one more subtle bit here: the standard library contains an @@ -225,19 +225,19 @@ //! often called 'iterator adapters', as they're a form of the 'adapter //! pattern'. //! -//! Common iterator adapters include [`map()`], [`take()`], and [`filter()`]. +//! Common iterator adapters include [`map`], [`take`], and [`filter`]. //! For more, see their documentation. //! -//! [`map()`]: trait.Iterator.html#method.map -//! [`take()`]: trait.Iterator.html#method.take -//! [`filter()`]: trait.Iterator.html#method.filter +//! [`map`]: trait.Iterator.html#method.map +//! [`take`]: trait.Iterator.html#method.take +//! [`filter`]: trait.Iterator.html#method.filter //! //! # Laziness //! //! Iterators (and iterator [adapters](#adapters)) are *lazy*. This means that //! just creating an iterator doesn't _do_ a whole lot. Nothing really happens -//! until you call [`next()`]. This is sometimes a source of confusion when -//! creating an iterator solely for its side effects. For example, the [`map()`] +//! until you call [`next`]. This is sometimes a source of confusion when +//! creating an iterator solely for its side effects. For example, the [`map`] //! method calls a closure on each element it iterates over: //! //! ``` @@ -254,7 +254,7 @@ //! do nothing unless consumed //! ``` //! -//! The idiomatic way to write a [`map()`] for its side effects is to use a +//! The idiomatic way to write a [`map`] for its side effects is to use a //! `for` loop instead: //! //! ``` @@ -265,12 +265,12 @@ //! } //! ``` //! -//! [`map()`]: trait.Iterator.html#method.map +//! [`map`]: trait.Iterator.html#method.map //! //! The two most common ways to evaluate an iterator are to use a `for` loop -//! like this, or using the [`collect()`] method to produce a new collection. +//! like this, or using the [`collect`] method to produce a new collection. //! -//! [`collect()`]: trait.Iterator.html#method.collect +//! [`collect`]: trait.Iterator.html#method.collect //! //! # Infinity //! @@ -281,7 +281,7 @@ //! let numbers = 0..; //! ``` //! -//! It is common to use the [`take()`] iterator adapter to turn an infinite +//! It is common to use the [`take`] iterator adapter to turn an infinite //! iterator into a finite one: //! //! ``` @@ -295,7 +295,7 @@ //! //! This will print the numbers `0` through `4`, each on their own line. //! -//! [`take()`]: trait.Iterator.html#method.take +//! [`take`]: trait.Iterator.html#method.take #![stable(feature = "rust1", since = "1.0.0")] @@ -338,10 +338,10 @@ mod traits; /// An double-ended iterator with the direction inverted. /// -/// This `struct` is created by the [`rev()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`rev`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`rev()`]: trait.Iterator.html#method.rev +/// [`rev`]: trait.Iterator.html#method.rev /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -389,10 +389,10 @@ unsafe impl TrustedLen for Rev /// An iterator that clones the elements of an underlying iterator. /// -/// This `struct` is created by the [`cloned()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`cloned`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`cloned()`]: trait.Iterator.html#method.cloned +/// [`cloned`]: trait.Iterator.html#method.cloned /// [`Iterator`]: trait.Iterator.html #[stable(feature = "iter_cloned", since = "1.1.0")] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -469,10 +469,10 @@ unsafe impl<'a, I, T: 'a> TrustedLen for Cloned /// An iterator that repeats endlessly. /// -/// This `struct` is created by the [`cycle()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`cycle`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`cycle()`]: trait.Iterator.html#method.cycle +/// [`cycle`]: trait.Iterator.html#method.cycle /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -510,10 +510,10 @@ impl FusedIterator for Cycle where I: Clone + Iterator {} /// An iterator that strings two iterators together. /// -/// This `struct` is created by the [`chain()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`chain`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`chain()`]: trait.Iterator.html#method.chain +/// [`chain`]: trait.Iterator.html#method.chain /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -703,10 +703,10 @@ unsafe impl TrustedLen for Chain /// An iterator that iterates two other iterators simultaneously. /// -/// This `struct` is created by the [`zip()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`zip`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`zip()`]: trait.Iterator.html#method.zip +/// [`zip`]: trait.Iterator.html#method.zip /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -925,16 +925,16 @@ unsafe impl TrustedLen for Zip /// An iterator that maps the values of `iter` with `f`. /// -/// This `struct` is created by the [`map()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`map`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`map()`]: trait.Iterator.html#method.map +/// [`map`]: trait.Iterator.html#method.map /// [`Iterator`]: trait.Iterator.html /// /// # Notes about side effects /// -/// The [`map()`] iterator implements [`DoubleEndedIterator`], meaning that -/// you can also [`map()`] backwards: +/// The [`map`] iterator implements [`DoubleEndedIterator`], meaning that +/// you can also [`map`] backwards: /// /// ```rust /// let v: Vec = vec![1, 2, 3].into_iter().map(|x| x + 1).rev().collect(); @@ -1058,10 +1058,10 @@ unsafe impl TrustedRandomAccess for Map /// An iterator that filters the elements of `iter` with `predicate`. /// -/// This `struct` is created by the [`filter()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`filter`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`filter()`]: trait.Iterator.html#method.filter +/// [`filter`]: trait.Iterator.html#method.filter /// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1142,10 +1142,10 @@ impl FusedIterator for Filter /// An iterator that uses `f` to both filter and map elements from `iter`. /// -/// This `struct` is created by the [`filter_map()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`filter_map`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`filter_map()`]: trait.Iterator.html#method.filter_map +/// [`filter_map`]: trait.Iterator.html#method.filter_map /// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1208,10 +1208,10 @@ impl FusedIterator for FilterMap /// An iterator that yields the current count and the element during iteration. /// -/// This `struct` is created by the [`enumerate()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`enumerate`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`enumerate()`]: trait.Iterator.html#method.enumerate +/// [`enumerate`]: trait.Iterator.html#method.enumerate /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -1317,10 +1317,10 @@ unsafe impl TrustedLen for Enumerate /// An iterator with a `peek()` that returns an optional reference to the next /// element. /// -/// This `struct` is created by the [`peekable()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`peekable`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`peekable()`]: trait.Iterator.html#method.peekable +/// [`peekable`]: trait.Iterator.html#method.peekable /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -1401,10 +1401,10 @@ impl FusedIterator for Peekable {} impl Peekable { /// Returns a reference to the next() value without advancing the iterator. /// - /// Like [`next()`], if there is a value, it is wrapped in a `Some(T)`. + /// Like [`next`], if there is a value, it is wrapped in a `Some(T)`. /// But if the iteration is over, `None` is returned. /// - /// [`next()`]: trait.Iterator.html#tymethod.next + /// [`next`]: trait.Iterator.html#tymethod.next /// /// Because `peek()` returns a reference, and many iterators iterate over /// references, there can be a possibly confusing situation where the @@ -1452,10 +1452,10 @@ impl Peekable { /// An iterator that rejects elements while `predicate` is true. /// -/// This `struct` is created by the [`skip_while()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`skip_while`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`skip_while()`]: trait.Iterator.html#method.skip_while +/// [`skip_while`]: trait.Iterator.html#method.skip_while /// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1506,10 +1506,10 @@ impl FusedIterator for SkipWhile /// An iterator that only accepts elements while `predicate` is true. /// -/// This `struct` is created by the [`take_while()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`take_while`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`take_while()`]: trait.Iterator.html#method.take_while +/// [`take_while`]: trait.Iterator.html#method.take_while /// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1565,10 +1565,10 @@ impl FusedIterator for TakeWhile /// An iterator that skips over `n` elements of `iter`. /// -/// This `struct` is created by the [`skip()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`skip`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`skip()`]: trait.Iterator.html#method.skip +/// [`skip`]: trait.Iterator.html#method.skip /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -1659,10 +1659,10 @@ impl FusedIterator for Skip where I: FusedIterator {} /// An iterator that only iterates over the first `n` iterations of `iter`. /// -/// This `struct` is created by the [`take()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`take`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`take()`]: trait.Iterator.html#method.take +/// [`take`]: trait.Iterator.html#method.take /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -1723,10 +1723,10 @@ impl FusedIterator for Take where I: FusedIterator {} /// An iterator to maintain state while iterating another iterator. /// -/// This `struct` is created by the [`scan()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`scan`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`scan()`]: trait.Iterator.html#method.scan +/// [`scan`]: trait.Iterator.html#method.scan /// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1773,10 +1773,10 @@ impl FusedIterator for Scan /// An iterator that maps each element to an iterator, and yields the elements /// of the produced iterators. /// -/// This `struct` is created by the [`flat_map()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`flat_map`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`flat_map()`]: trait.Iterator.html#method.flat_map +/// [`flat_map`]: trait.Iterator.html#method.flat_map /// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1863,10 +1863,10 @@ impl FusedIterator for FlatMap /// An iterator that yields `None` forever after the underlying iterator /// yields `None` once. /// -/// This `struct` is created by the [`fuse()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`fuse`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`fuse()`]: trait.Iterator.html#method.fuse +/// [`fuse`]: trait.Iterator.html#method.fuse /// [`Iterator`]: trait.Iterator.html #[derive(Clone, Debug)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] @@ -2012,10 +2012,10 @@ impl ExactSizeIterator for Fuse where I: ExactSizeIterator { /// An iterator that calls a function with a reference to each element before /// yielding it. /// -/// This `struct` is created by the [`inspect()`] method on [`Iterator`]. See its +/// This `struct` is created by the [`inspect`] method on [`Iterator`]. See its /// documentation for more. /// -/// [`inspect()`]: trait.Iterator.html#method.inspect +/// [`inspect`]: trait.Iterator.html#method.inspect /// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libcore/iter/sources.rs b/src/libcore/iter/sources.rs index b988ce73bde..b405f35d5e4 100644 --- a/src/libcore/iter/sources.rs +++ b/src/libcore/iter/sources.rs @@ -16,9 +16,9 @@ use super::{FusedIterator, TrustedLen}; /// An iterator that repeats an element endlessly. /// -/// This `struct` is created by the [`repeat()`] function. See its documentation for more. +/// This `struct` is created by the [`repeat`] function. See its documentation for more. /// -/// [`repeat()`]: fn.repeat.html +/// [`repeat`]: fn.repeat.html #[derive(Clone, Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct Repeat { @@ -50,9 +50,9 @@ impl FusedIterator for Repeat {} /// over and over and 🔁. /// /// Infinite iterators like `repeat()` are often used with adapters like -/// [`take()`], in order to make them finite. +/// [`take`], in order to make them finite. /// -/// [`take()`]: trait.Iterator.html#method.take +/// [`take`]: trait.Iterator.html#method.take /// /// # Examples /// @@ -74,7 +74,7 @@ impl FusedIterator for Repeat {} /// assert_eq!(Some(4), fours.next()); /// ``` /// -/// Going finite with [`take()`]: +/// Going finite with [`take`]: /// /// ``` /// use std::iter; @@ -98,9 +98,9 @@ pub fn repeat(elt: T) -> Repeat { /// An iterator that yields nothing. /// -/// This `struct` is created by the [`empty()`] function. See its documentation for more. +/// This `struct` is created by the [`empty`] function. See its documentation for more. /// -/// [`empty()`]: fn.empty.html +/// [`empty`]: fn.empty.html #[stable(feature = "iter_empty", since = "1.2.0")] pub struct Empty(marker::PhantomData); @@ -183,9 +183,9 @@ pub fn empty() -> Empty { /// An iterator that yields an element exactly once. /// -/// This `struct` is created by the [`once()`] function. See its documentation for more. +/// This `struct` is created by the [`once`] function. See its documentation for more. /// -/// [`once()`]: fn.once.html +/// [`once`]: fn.once.html #[derive(Clone, Debug)] #[stable(feature = "iter_once", since = "1.2.0")] pub struct Once { @@ -227,12 +227,12 @@ impl FusedIterator for Once {} /// Creates an iterator that yields an element exactly once. /// -/// This is commonly used to adapt a single value into a [`chain()`] of other +/// This is commonly used to adapt a single value into a [`chain`] of other /// kinds of iteration. Maybe you have an iterator that covers almost /// everything, but you need an extra special case. Maybe you have a function /// which works on iterators, but you only need to process one value. /// -/// [`chain()`]: trait.Iterator.html#method.chain +/// [`chain`]: trait.Iterator.html#method.chain /// /// # Examples /// diff --git a/src/libcore/iter/traits.rs b/src/libcore/iter/traits.rs index cb180110d3c..3415b0eea9b 100644 --- a/src/libcore/iter/traits.rs +++ b/src/libcore/iter/traits.rs @@ -16,13 +16,13 @@ use num::Wrapping; /// created from an iterator. This is common for types which describe a /// collection of some kind. /// -/// `FromIterator`'s [`from_iter()`] is rarely called explicitly, and is instead -/// used through [`Iterator`]'s [`collect()`] method. See [`collect()`]'s +/// `FromIterator`'s [`from_iter`] is rarely called explicitly, and is instead +/// used through [`Iterator`]'s [`collect`] method. See [`collect`]'s /// documentation for more examples. /// -/// [`from_iter()`]: #tymethod.from_iter +/// [`from_iter`]: #tymethod.from_iter /// [`Iterator`]: trait.Iterator.html -/// [`collect()`]: trait.Iterator.html#method.collect +/// [`collect`]: trait.Iterator.html#method.collect /// /// See also: [`IntoIterator`]. /// @@ -42,7 +42,7 @@ use num::Wrapping; /// assert_eq!(v, vec![5, 5, 5, 5, 5]); /// ``` /// -/// Using [`collect()`] to implicitly use `FromIterator`: +/// Using [`collect`] to implicitly use `FromIterator`: /// /// ``` /// let five_fives = std::iter::repeat(5).take(5); @@ -487,17 +487,17 @@ impl<'a, I: DoubleEndedIterator + ?Sized> DoubleEndedIterator for &'a mut I { /// backwards, a good start is to know where the end is. /// /// When implementing an `ExactSizeIterator`, You must also implement -/// [`Iterator`]. When doing so, the implementation of [`size_hint()`] *must* +/// [`Iterator`]. When doing so, the implementation of [`size_hint`] *must* /// return the exact size of the iterator. /// /// [`Iterator`]: trait.Iterator.html -/// [`size_hint()`]: trait.Iterator.html#method.size_hint +/// [`size_hint`]: trait.Iterator.html#method.size_hint /// -/// The [`len()`] method has a default implementation, so you usually shouldn't +/// The [`len`] method has a default implementation, so you usually shouldn't /// implement it. However, you may be able to provide a more performant /// implementation than the default, so overriding it in this case makes sense. /// -/// [`len()`]: #method.len +/// [`len`]: #method.len /// /// # Examples /// @@ -557,11 +557,11 @@ pub trait ExactSizeIterator: Iterator { /// implementation, you can do so. See the [trait-level] docs for an /// example. /// - /// This function has the same safety guarantees as the [`size_hint()`] + /// This function has the same safety guarantees as the [`size_hint`] /// function. /// /// [trait-level]: trait.ExactSizeIterator.html - /// [`size_hint()`]: trait.Iterator.html#method.size_hint + /// [`size_hint`]: trait.Iterator.html#method.size_hint /// /// # Examples /// @@ -624,14 +624,14 @@ impl<'a, I: ExactSizeIterator + ?Sized> ExactSizeIterator for &'a mut I { /// Trait to represent types that can be created by summing up an iterator. /// -/// This trait is used to implement the [`sum()`] method on iterators. Types which -/// implement the trait can be generated by the [`sum()`] method. Like +/// This trait is used to implement the [`sum`] method on iterators. Types which +/// implement the trait can be generated by the [`sum`] method. Like /// [`FromIterator`] this trait should rarely be called directly and instead -/// interacted with through [`Iterator::sum()`]. +/// interacted with through [`Iterator::sum`]. /// -/// [`sum()`]: ../../std/iter/trait.Sum.html#tymethod.sum +/// [`sum`]: ../../std/iter/trait.Sum.html#tymethod.sum /// [`FromIterator`]: ../../std/iter/trait.FromIterator.html -/// [`Iterator::sum()`]: ../../std/iter/trait.Iterator.html#method.sum +/// [`Iterator::sum`]: ../../std/iter/trait.Iterator.html#method.sum #[stable(feature = "iter_arith_traits", since = "1.12.0")] pub trait Sum: Sized { /// Method which takes an iterator and generates `Self` from the elements by @@ -643,14 +643,14 @@ pub trait Sum: Sized { /// Trait to represent types that can be created by multiplying elements of an /// iterator. /// -/// This trait is used to implement the [`product()`] method on iterators. Types -/// which implement the trait can be generated by the [`product()`] method. Like +/// This trait is used to implement the [`product`] method on iterators. Types +/// which implement the trait can be generated by the [`product`] method. Like /// [`FromIterator`] this trait should rarely be called directly and instead -/// interacted with through [`Iterator::product()`]. +/// interacted with through [`Iterator::product`]. /// -/// [`product()`]: ../../std/iter/trait.Product.html#tymethod.product +/// [`product`]: ../../std/iter/trait.Product.html#tymethod.product /// [`FromIterator`]: ../../std/iter/trait.FromIterator.html -/// [`Iterator::product()`]: ../../std/iter/trait.Iterator.html#method.product +/// [`Iterator::product`]: ../../std/iter/trait.Iterator.html#method.product #[stable(feature = "iter_arith_traits", since = "1.12.0")] pub trait Product: Sized { /// Method which takes an iterator and generates `Self` from the elements by @@ -823,12 +823,12 @@ impl Product> for Result /// that behave this way because it allows for some significant optimizations. /// /// Note: In general, you should not use `FusedIterator` in generic bounds if -/// you need a fused iterator. Instead, you should just call [`Iterator::fuse()`] +/// you need a fused iterator. Instead, you should just call [`Iterator::fuse`] /// on the iterator. If the iterator is already fused, the additional [`Fuse`] /// wrapper will be a no-op with no performance penalty. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None -/// [`Iterator::fuse()`]: ../../std/iter/trait.Iterator.html#method.fuse +/// [`Iterator::fuse`]: ../../std/iter/trait.Iterator.html#method.fuse /// [`Fuse`]: ../../std/iter/struct.Fuse.html #[unstable(feature = "fused", issue = "35602")] pub trait FusedIterator: Iterator {} @@ -848,11 +848,11 @@ impl<'a, I: FusedIterator + ?Sized> FusedIterator for &'a mut I {} /// # Safety /// /// This trait must only be implemented when the contract is upheld. -/// Consumers of this trait must inspect [`.size_hint()`]’s upper bound. +/// Consumers of this trait must inspect [`.size_hint`]’s upper bound. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None /// [`usize::MAX`]: ../../std/usize/constant.MAX.html -/// [`.size_hint()`]: ../../std/iter/trait.Iterator.html#method.size_hint +/// [`.size_hint`]: ../../std/iter/trait.Iterator.html#method.size_hint #[unstable(feature = "trusted_len", issue = "37572")] pub unsafe trait TrustedLen : Iterator {} diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index b22f7fa1707..021079f85f6 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -90,10 +90,10 @@ macro_rules! assert { /// On panic, this macro will print the values of the expressions with their /// debug representations. /// -/// Like [`assert!()`], this macro has a second version, where a custom +/// Like [`assert!`], this macro has a second version, where a custom /// panic message can be provided. /// -/// [`assert!()`]: macro.assert.html +/// [`assert!`]: macro.assert.html /// /// # Examples /// diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 1e9eaaf5f32..393c01b0105 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -245,7 +245,7 @@ pub trait Unsize { /// [`String`]'s buffer, leading to a double free. /// /// Generalizing the latter case, any type implementing [`Drop`] can't be `Copy`, because it's -/// managing some resource besides its own [`size_of::()`] bytes. +/// managing some resource besides its own [`size_of::`] bytes. /// /// If you try to implement `Copy` on a struct or enum containing non-`Copy` data, you will get /// the error [E0204]. @@ -262,7 +262,7 @@ pub trait Unsize { /// [`Vec`]: ../../std/vec/struct.Vec.html /// [`String`]: ../../std/string/struct.String.html /// [`Drop`]: ../../std/ops/trait.Drop.html -/// [`size_of::()`]: ../../std/mem/fn.size_of.html +/// [`size_of::`]: ../../std/mem/fn.size_of.html /// [`Clone`]: ../clone/trait.Clone.html /// [`String`]: ../../std/string/struct.String.html /// [`i32`]: ../../std/primitive.i32.html diff --git a/src/libcore/mem.rs b/src/libcore/mem.rs index f4ce4697d7c..ba65e4494a8 100644 --- a/src/libcore/mem.rs +++ b/src/libcore/mem.rs @@ -617,7 +617,7 @@ pub fn drop(_x: T) { } /// the contained value. /// /// This function will unsafely assume the pointer `src` is valid for -/// [`size_of::()`][size_of] bytes by transmuting `&T` to `&U` and then reading +/// [`size_of::`][size_of] bytes by transmuting `&T` to `&U` and then reading /// the `&U`. It will also unsafely create a copy of the contained value instead of /// moving out of `src`. /// diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs index 97ea6bb347b..81c80ba5115 100644 --- a/src/libcore/num/mod.rs +++ b/src/libcore/num/mod.rs @@ -2390,11 +2390,11 @@ impl usize { /// A classification of floating point numbers. /// -/// This `enum` is used as the return type for [`f32::classify()`] and [`f64::classify()`]. See +/// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See /// their documentation for more. /// -/// [`f32::classify()`]: ../../std/primitive.f32.html#method.classify -/// [`f64::classify()`]: ../../std/primitive.f64.html#method.classify +/// [`f32::classify`]: ../../std/primitive.f32.html#method.classify +/// [`f64::classify`]: ../../std/primitive.f64.html#method.classify /// /// # Examples /// @@ -2756,9 +2756,9 @@ fn from_str_radix(src: &str, radix: u32) -> Result> Range { /// A range which is only bounded below: { x | start <= x }. /// Use `start..` for its shorthand. /// -/// See the [`contains()`](#method.contains) method for its characterization. +/// See the [`contains`](#method.contains) method for its characterization. /// /// Note: Currently, no overflow checking is done for the iterator /// implementation; if you use an integer range and the integer overflows, it @@ -2141,7 +2141,7 @@ impl> RangeFrom { /// A range which is only bounded above: { x | x < end }. /// Use `..end` (two dots) for its shorthand. /// -/// See the [`contains()`](#method.contains) method for its characterization. +/// See the [`contains`](#method.contains) method for its characterization. /// /// It cannot serve as an iterator because it doesn't have a starting point. /// @@ -2207,7 +2207,7 @@ impl> RangeTo { /// An inclusive range which is bounded at both ends: { x | start <= x <= end }. /// Use `start...end` (three dots) for its shorthand. /// -/// See the [`contains()`](#method.contains) method for its characterization. +/// See the [`contains`](#method.contains) method for its characterization. /// /// # Examples /// @@ -2293,7 +2293,7 @@ impl> RangeInclusive { /// An inclusive range which is only bounded above: { x | x <= end }. /// Use `...end` (three dots) for its shorthand. /// -/// See the [`contains()`](#method.contains) method for its characterization. +/// See the [`contains`](#method.contains) method for its characterization. /// /// It cannot serve as an iterator because it doesn't have a starting point. /// diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 52e33016310..395a84460a9 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -28,12 +28,12 @@ pub mod pattern; /// A trait to abstract the idea of creating a new instance of a type from a /// string. /// -/// `FromStr`'s [`from_str()`] method is often used implicitly, through -/// [`str`]'s [`parse()`] method. See [`parse()`]'s documentation for examples. +/// `FromStr`'s [`from_str`] method is often used implicitly, through +/// [`str`]'s [`parse`] method. See [`parse`]'s documentation for examples. /// -/// [`from_str()`]: #tymethod.from_str +/// [`from_str`]: #tymethod.from_str /// [`str`]: ../../std/primitive.str.html -/// [`parse()`]: ../../std/primitive.str.html#method.parse +/// [`parse`]: ../../std/primitive.str.html#method.parse #[stable(feature = "rust1", since = "1.0.0")] pub trait FromStr: Sized { /// The associated error which can be returned from parsing. @@ -164,13 +164,13 @@ impl Utf8Error { /// /// If you are sure that the byte slice is valid UTF-8, and you don't want to /// incur the overhead of the validity check, there is an unsafe version of -/// this function, [`from_utf8_unchecked()`][fromutf8u], which has the same +/// this function, [`from_utf8_unchecked`][fromutf8u], which has the same /// behavior but skips the check. /// /// [fromutf8u]: fn.from_utf8_unchecked.html /// /// If you need a `String` instead of a `&str`, consider -/// [`String::from_utf8()`][string]. +/// [`String::from_utf8`][string]. /// /// [string]: ../../std/string/struct.String.html#method.from_utf8 /// @@ -265,7 +265,7 @@ unsafe fn from_raw_parts_mut<'a>(p: *mut u8, len: usize) -> &'a mut str { /// Converts a slice of bytes to a string slice without checking /// that the string contains valid UTF-8. /// -/// See the safe version, [`from_utf8()`][fromutf8], for more information. +/// See the safe version, [`from_utf8`][fromutf8], for more information. /// /// [fromutf8]: fn.from_utf8.html /// @@ -310,9 +310,9 @@ Section: Iterators /// Iterator for the char (representing *Unicode Scalar Values*) of a string /// -/// Created with the method [`chars()`]. +/// Created with the method [`chars`]. /// -/// [`chars()`]: ../../std/primitive.str.html#method.chars +/// [`chars`]: ../../std/primitive.str.html#method.chars #[derive(Clone, Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct Chars<'a> { @@ -567,9 +567,9 @@ impl<'a> CharIndices<'a> { /// External iterator for a string's bytes. /// Use with the `std::iter` module. /// -/// Created with the method [`bytes()`]. +/// Created with the method [`bytes`]. /// -/// [`bytes()`]: ../../std/primitive.str.html#method.bytes +/// [`bytes`]: ../../std/primitive.str.html#method.bytes #[stable(feature = "rust1", since = "1.0.0")] #[derive(Clone, Debug)] pub struct Bytes<'a>(Cloned>); @@ -902,14 +902,14 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> { generate_pattern_iterators! { forward: - /// Created with the method [`split()`]. + /// Created with the method [`split`]. /// - /// [`split()`]: ../../std/primitive.str.html#method.split + /// [`split`]: ../../std/primitive.str.html#method.split struct Split; reverse: - /// Created with the method [`rsplit()`]. + /// Created with the method [`rsplit`]. /// - /// [`rsplit()`]: ../../std/primitive.str.html#method.rsplit + /// [`rsplit`]: ../../std/primitive.str.html#method.rsplit struct RSplit; stability: #[stable(feature = "rust1", since = "1.0.0")] @@ -920,14 +920,14 @@ generate_pattern_iterators! { generate_pattern_iterators! { forward: - /// Created with the method [`split_terminator()`]. + /// Created with the method [`split_terminator`]. /// - /// [`split_terminator()`]: ../../std/primitive.str.html#method.split_terminator + /// [`split_terminator`]: ../../std/primitive.str.html#method.split_terminator struct SplitTerminator; reverse: - /// Created with the method [`rsplit_terminator()`]. + /// Created with the method [`rsplit_terminator`]. /// - /// [`rsplit_terminator()`]: ../../std/primitive.str.html#method.rsplit_terminator + /// [`rsplit_terminator`]: ../../std/primitive.str.html#method.rsplit_terminator struct RSplitTerminator; stability: #[stable(feature = "rust1", since = "1.0.0")] @@ -980,14 +980,14 @@ impl<'a, P: Pattern<'a>> SplitNInternal<'a, P> { generate_pattern_iterators! { forward: - /// Created with the method [`splitn()`]. + /// Created with the method [`splitn`]. /// - /// [`splitn()`]: ../../std/primitive.str.html#method.splitn + /// [`splitn`]: ../../std/primitive.str.html#method.splitn struct SplitN; reverse: - /// Created with the method [`rsplitn()`]. + /// Created with the method [`rsplitn`]. /// - /// [`rsplitn()`]: ../../std/primitive.str.html#method.rsplitn + /// [`rsplitn`]: ../../std/primitive.str.html#method.rsplitn struct RSplitN; stability: #[stable(feature = "rust1", since = "1.0.0")] @@ -1031,14 +1031,14 @@ impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> { generate_pattern_iterators! { forward: - /// Created with the method [`match_indices()`]. + /// Created with the method [`match_indices`]. /// - /// [`match_indices()`]: ../../std/primitive.str.html#method.match_indices + /// [`match_indices`]: ../../std/primitive.str.html#method.match_indices struct MatchIndices; reverse: - /// Created with the method [`rmatch_indices()`]. + /// Created with the method [`rmatch_indices`]. /// - /// [`rmatch_indices()`]: ../../std/primitive.str.html#method.rmatch_indices + /// [`rmatch_indices`]: ../../std/primitive.str.html#method.rmatch_indices struct RMatchIndices; stability: #[stable(feature = "str_match_indices", since = "1.5.0")] @@ -1084,14 +1084,14 @@ impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> { generate_pattern_iterators! { forward: - /// Created with the method [`matches()`]. + /// Created with the method [`matches`]. /// - /// [`matches()`]: ../../std/primitive.str.html#method.matches + /// [`matches`]: ../../std/primitive.str.html#method.matches struct Matches; reverse: - /// Created with the method [`rmatches()`]. + /// Created with the method [`rmatches`]. /// - /// [`rmatches()`]: ../../std/primitive.str.html#method.rmatches + /// [`rmatches`]: ../../std/primitive.str.html#method.rmatches struct RMatches; stability: #[stable(feature = "str_matches", since = "1.2.0")] @@ -1100,9 +1100,9 @@ generate_pattern_iterators! { delegate double ended; } -/// Created with the method [`lines()`]. +/// Created with the method [`lines`]. /// -/// [`lines()`]: ../../std/primitive.str.html#method.lines +/// [`lines`]: ../../std/primitive.str.html#method.lines #[stable(feature = "rust1", since = "1.0.0")] #[derive(Clone, Debug)] pub struct Lines<'a>(Map, LinesAnyMap>); @@ -1133,9 +1133,9 @@ impl<'a> DoubleEndedIterator for Lines<'a> { #[unstable(feature = "fused", issue = "35602")] impl<'a> FusedIterator for Lines<'a> {} -/// Created with the method [`lines_any()`]. +/// Created with the method [`lines_any`]. /// -/// [`lines_any()`]: ../../std/primitive.str.html#method.lines_any +/// [`lines_any`]: ../../std/primitive.str.html#method.lines_any #[stable(feature = "rust1", since = "1.0.0")] #[rustc_deprecated(since = "1.4.0", reason = "use lines()/Lines instead now")] #[derive(Clone, Debug)] diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index e5562d05f10..b074e8b86b9 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -142,14 +142,14 @@ pub struct DirEntry(fs_imp::DirEntry); /// [`File::open`]: struct.File.html#method.open /// [`File::create`]: struct.File.html#method.create /// -/// Generally speaking, when using `OpenOptions`, you'll first call [`new()`], -/// then chain calls to methods to set each option, then call [`open()`], +/// Generally speaking, when using `OpenOptions`, you'll first call [`new`], +/// then chain calls to methods to set each option, then call [`open`], /// passing the path of the file you're trying to open. This will give you a /// [`io::Result`][result] with a [`File`][file] inside that you can further /// operate on. /// -/// [`new()`]: struct.OpenOptions.html#method.new -/// [`open()`]: struct.OpenOptions.html#method.open +/// [`new`]: struct.OpenOptions.html#method.new +/// [`open`]: struct.OpenOptions.html#method.open /// [result]: ../io/type.Result.html /// [file]: struct.File.html /// diff --git a/src/libstd/io/error.rs b/src/libstd/io/error.rs index 6d4da2e6a88..fb67eaf3c63 100644 --- a/src/libstd/io/error.rs +++ b/src/libstd/io/error.rs @@ -140,13 +140,13 @@ pub enum ErrorKind { #[stable(feature = "rust1", since = "1.0.0")] TimedOut, /// An error returned when an operation could not be completed because a - /// call to [`write()`] returned [`Ok(0)`]. + /// call to [`write`] returned [`Ok(0)`]. /// /// This typically means that an operation could only succeed if it wrote a /// particular number of bytes but only a smaller number of bytes could be /// written. /// - /// [`write()`]: ../../std/io/trait.Write.html#tymethod.write + /// [`write`]: ../../std/io/trait.Write.html#tymethod.write /// [`Ok(0)`]: ../../std/io/type.Result.html #[stable(feature = "rust1", since = "1.0.0")] WriteZero, diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 58788cdcd4c..850885a8c0f 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -21,7 +21,7 @@ //! of other types, and you can implement them for your types too. As such, //! you'll see a few different types of I/O throughout the documentation in //! this module: [`File`]s, [`TcpStream`]s, and sometimes even [`Vec`]s. For -//! example, [`Read`] adds a [`read()`] method, which we can use on `File`s: +//! example, [`Read`] adds a [`read`] method, which we can use on `File`s: //! //! ``` //! use std::io; @@ -106,7 +106,7 @@ //! ``` //! //! [`BufWriter`] doesn't add any new ways of writing; it just buffers every call -//! to [`write()`]: +//! to [`write`]: //! //! ``` //! use std::io; @@ -157,7 +157,7 @@ //! # } //! ``` //! -//! Of course, using [`io::stdout()`] directly is less common than something like +//! Of course, using [`io::stdout`] directly is less common than something like //! [`println!`]. //! //! ## Iterator types @@ -245,13 +245,13 @@ //! [`Vec`]: ../vec/struct.Vec.html //! [`BufReader`]: struct.BufReader.html //! [`BufWriter`]: struct.BufWriter.html -//! [`write()`]: trait.Write.html#tymethod.write -//! [`io::stdout()`]: fn.stdout.html +//! [`write`]: trait.Write.html#tymethod.write +//! [`io::stdout`]: fn.stdout.html //! [`println!`]: ../macro.println.html //! [`Lines`]: struct.Lines.html //! [`io::Result`]: type.Result.html //! [`?` operator]: ../../book/syntax-index.html -//! [`read()`]: trait.Read.html#tymethod.read +//! [`read`]: trait.Read.html#tymethod.read #![stable(feature = "rust1", since = "1.0.0")] @@ -530,7 +530,7 @@ pub trait Read { /// If the data in this stream is *not* valid UTF-8 then an error is /// returned and `buf` is unchanged. /// - /// See [`read_to_end()`][readtoend] for other error semantics. + /// See [`read_to_end`][readtoend] for other error semantics. /// /// [readtoend]: #method.read_to_end /// @@ -815,12 +815,12 @@ pub trait Read { /// /// Implementors of the `Write` trait are sometimes called 'writers'. /// -/// Writers are defined by two required methods, [`write()`] and [`flush()`]: +/// Writers are defined by two required methods, [`write`] and [`flush`]: /// -/// * The [`write()`] method will attempt to write some data into the object, +/// * The [`write`] method will attempt to write some data into the object, /// returning how many bytes were successfully written. /// -/// * The [`flush()`] method is useful for adaptors and explicit buffers +/// * The [`flush`] method is useful for adaptors and explicit buffers /// themselves for ensuring that all buffered data has been pushed out to the /// 'true sink'. /// @@ -828,8 +828,8 @@ pub trait Read { /// throughout [`std::io`] take and provide types which implement the `Write` /// trait. /// -/// [`write()`]: #tymethod.write -/// [`flush()`]: #tymethod.flush +/// [`write`]: #tymethod.write +/// [`flush`]: #tymethod.flush /// [`std::io`]: index.html /// /// # Examples @@ -1159,7 +1159,7 @@ fn read_until(r: &mut R, delim: u8, buf: &mut Vec) /// /// For example, reading line-by-line is inefficient without using a buffer, so /// if you want to read by line, you'll need `BufRead`, which includes a -/// [`read_line()`] method as well as a [`lines()`] iterator. +/// [`read_line`] method as well as a [`lines`] iterator. /// /// # Examples /// @@ -1183,8 +1183,8 @@ fn read_until(r: &mut R, delim: u8, buf: &mut Vec) /// /// [`BufReader`]: struct.BufReader.html /// [`File`]: ../fs/struct.File.html -/// [`read_line()`]: #method.read_line -/// [`lines()`]: #method.lines +/// [`read_line`]: #method.read_line +/// [`lines`]: #method.lines /// [`Read`]: trait.Read.html /// /// ``` @@ -1209,13 +1209,13 @@ pub trait BufRead: Read { /// Fills the internal buffer of this object, returning the buffer contents. /// /// This function is a lower-level call. It needs to be paired with the - /// [`consume()`] method to function properly. When calling this + /// [`consume`] method to function properly. When calling this /// method, none of the contents will be "read" in the sense that later - /// calling `read` may return the same contents. As such, [`consume()`] must + /// calling `read` may return the same contents. As such, [`consume`] must /// be called with the number of bytes that are consumed from this buffer to /// ensure that the bytes are never returned twice. /// - /// [`consume()`]: #tymethod.consume + /// [`consume`]: #tymethod.consume /// /// An empty buffer returned indicates that the stream has reached EOF. /// @@ -1256,21 +1256,21 @@ pub trait BufRead: Read { /// so they should no longer be returned in calls to `read`. /// /// This function is a lower-level call. It needs to be paired with the - /// [`fill_buf()`] method to function properly. This function does + /// [`fill_buf`] method to function properly. This function does /// not perform any I/O, it simply informs this object that some amount of - /// its buffer, returned from [`fill_buf()`], has been consumed and should + /// its buffer, returned from [`fill_buf`], has been consumed and should /// no longer be returned. As such, this function may do odd things if - /// [`fill_buf()`] isn't called before calling it. + /// [`fill_buf`] isn't called before calling it. /// /// The `amt` must be `<=` the number of bytes in the buffer returned by - /// [`fill_buf()`]. + /// [`fill_buf`]. /// /// # Examples /// - /// Since `consume()` is meant to be used with [`fill_buf()`], + /// Since `consume()` is meant to be used with [`fill_buf`], /// that method's example includes an example of `consume()`. /// - /// [`fill_buf()`]: #tymethod.fill_buf + /// [`fill_buf`]: #tymethod.fill_buf #[stable(feature = "rust1", since = "1.0.0")] fn consume(&mut self, amt: usize); @@ -1285,7 +1285,7 @@ pub trait BufRead: Read { /// # Errors /// /// This function will ignore all instances of [`ErrorKind::Interrupted`] and - /// will otherwise return any errors returned by [`fill_buf()`]. + /// will otherwise return any errors returned by [`fill_buf`]. /// /// If an I/O error is encountered then all bytes read so far will be /// present in `buf` and its length will have been adjusted appropriately. @@ -1295,7 +1295,7 @@ pub trait BufRead: Read { /// A locked standard input implements `BufRead`. In this example, we'll /// read from standard input until we see an `a` byte. /// - /// [`fill_buf()`]: #tymethod.fill_buf + /// [`fill_buf`]: #tymethod.fill_buf /// [`ErrorKind::Interrupted`]: enum.ErrorKind.html#variant.Interrupted /// /// ``` @@ -1330,7 +1330,7 @@ pub trait BufRead: Read { /// /// # Errors /// - /// This function has the same error semantics as [`read_until()`] and will + /// This function has the same error semantics as [`read_until`] and will /// also return an error if the read bytes are not valid UTF-8. If an I/O /// error is encountered then `buf` may contain some bytes already read in /// the event that all data read so far was valid UTF-8. @@ -1339,11 +1339,11 @@ pub trait BufRead: Read { /// /// A locked standard input implements `BufRead`. In this example, we'll /// read all of the lines from standard input. If we were to do this in - /// an actual project, the [`lines()`] method would be easier, of + /// an actual project, the [`lines`] method would be easier, of /// course. /// - /// [`lines()`]: #method.lines - /// [`read_until()`]: #method.read_until + /// [`lines`]: #method.lines + /// [`read_until`]: #method.read_until /// /// ``` /// use std::io; @@ -1375,7 +1375,7 @@ pub trait BufRead: Read { /// [`io::Result`]`<`[`Vec`]`>`. Each vector returned will *not* have /// the delimiter byte at the end. /// - /// This function will yield errors whenever [`read_until()`] would have + /// This function will yield errors whenever [`read_until`] would have /// also yielded an error. /// /// # Examples @@ -1385,7 +1385,7 @@ pub trait BufRead: Read { /// /// [`io::Result`]: type.Result.html /// [`Vec`]: ../vec/struct.Vec.html - /// [`read_until()`]: #method.read_until + /// [`read_until`]: #method.read_until /// /// ``` /// use std::io; @@ -1428,9 +1428,9 @@ pub trait BufRead: Read { /// /// # Errors /// - /// Each line of the iterator has the same error semantics as [`BufRead::read_line()`]. + /// Each line of the iterator has the same error semantics as [`BufRead::read_line`]. /// - /// [`BufRead::read_line()`]: trait.BufRead.html#method.read_line + /// [`BufRead::read_line`]: trait.BufRead.html#method.read_line #[stable(feature = "rust1", since = "1.0.0")] fn lines(self) -> Lines where Self: Sized { Lines { buf: self } @@ -1439,10 +1439,10 @@ pub trait BufRead: Read { /// Adaptor to chain together two readers. /// -/// This struct is generally created by calling [`chain()`] on a reader. -/// Please see the documentation of [`chain()`] for more details. +/// This struct is generally created by calling [`chain`] on a reader. +/// Please see the documentation of [`chain`] for more details. /// -/// [`chain()`]: trait.Read.html#method.chain +/// [`chain`]: trait.Read.html#method.chain #[stable(feature = "rust1", since = "1.0.0")] pub struct Chain { first: T, @@ -1496,10 +1496,10 @@ impl BufRead for Chain { /// Reader adaptor which limits the bytes read from an underlying reader. /// -/// This struct is generally created by calling [`take()`] on a reader. -/// Please see the documentation of [`take()`] for more details. +/// This struct is generally created by calling [`take`] on a reader. +/// Please see the documentation of [`take`] for more details. /// -/// [`take()`]: trait.Read.html#method.take +/// [`take`]: trait.Read.html#method.take #[stable(feature = "rust1", since = "1.0.0")] #[derive(Debug)] pub struct Take { @@ -1614,10 +1614,10 @@ fn read_one_byte(reader: &mut Read) -> Option> { /// An iterator over `u8` values of a reader. /// -/// This struct is generally created by calling [`bytes()`] on a reader. -/// Please see the documentation of [`bytes()`] for more details. +/// This struct is generally created by calling [`bytes`] on a reader. +/// Please see the documentation of [`bytes`] for more details. /// -/// [`bytes()`]: trait.Read.html#method.bytes +/// [`bytes`]: trait.Read.html#method.bytes #[stable(feature = "rust1", since = "1.0.0")] #[derive(Debug)] pub struct Bytes { @@ -1635,7 +1635,7 @@ impl Iterator for Bytes { /// An iterator over the `char`s of a reader. /// -/// This struct is generally created by calling [`chars()`][chars] on a reader. +/// This struct is generally created by calling [`chars`][chars] on a reader. /// Please see the documentation of `chars()` for more details. /// /// [chars]: trait.Read.html#method.chars @@ -1726,7 +1726,7 @@ impl fmt::Display for CharsError { /// An iterator over the contents of an instance of `BufRead` split on a /// particular byte. /// -/// This struct is generally created by calling [`split()`][split] on a +/// This struct is generally created by calling [`split`][split] on a /// `BufRead`. Please see the documentation of `split()` for more details. /// /// [split]: trait.BufRead.html#method.split @@ -1758,7 +1758,7 @@ impl Iterator for Split { /// An iterator over the lines of an instance of `BufRead`. /// -/// This struct is generally created by calling [`lines()`][lines] on a +/// This struct is generally created by calling [`lines`][lines] on a /// `BufRead`. Please see the documentation of `lines()` for more details. /// /// [lines]: trait.BufRead.html#method.lines diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index e16e8019b5f..38ad23e14b3 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -332,11 +332,11 @@ impl<'a> fmt::Debug for StdinLock<'a> { /// /// Each handle shares a global buffer of data to be written to the standard /// output stream. Access is also synchronized via a lock and explicit control -/// over locking is available via the [`lock()`] method. +/// over locking is available via the [`lock`] method. /// /// Created by the [`io::stdout`] method. /// -/// [`lock()`]: #method.lock +/// [`lock`]: #method.lock /// [`io::stdout`]: fn.stdout.html #[stable(feature = "rust1", since = "1.0.0")] pub struct Stdout { diff --git a/src/libstd/io/util.rs b/src/libstd/io/util.rs index 4163187488e..078f1ad3f6c 100644 --- a/src/libstd/io/util.rs +++ b/src/libstd/io/util.rs @@ -63,7 +63,7 @@ pub fn copy(reader: &mut R, writer: &mut W) -> io::Result< /// A reader which is always at EOF. /// -/// This struct is generally created by calling [`empty()`][empty]. Please see +/// This struct is generally created by calling [`empty`][empty]. Please see /// the documentation of `empty()` for more details. /// /// [empty]: fn.empty.html @@ -107,7 +107,7 @@ impl fmt::Debug for Empty { /// A reader which yields one byte over and over and over and over and over and... /// -/// This struct is generally created by calling [`repeat()`][repeat]. Please +/// This struct is generally created by calling [`repeat`][repeat]. Please /// see the documentation of `repeat()` for more details. /// /// [repeat]: fn.repeat.html @@ -150,7 +150,7 @@ impl fmt::Debug for Repeat { /// A writer which will move data into the void. /// -/// This struct is generally created by calling [`sink()`][sink]. Please +/// This struct is generally created by calling [`sink`][sink]. Please /// see the documentation of `sink()` for more details. /// /// [sink]: fn.sink.html diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 070690773b6..a6ea890c3ee 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -21,7 +21,7 @@ //! contained an `extern crate std;` import at the [crate root]. Therefore the //! standard library can be accessed in [`use`] statements through the path //! `std`, as in [`use std::env`], or in expressions through the absolute path -//! `::std`, as in [`::std::env::args()`]. +//! `::std`, as in [`::std::env::args`]. //! //! # How to read this documentation //! @@ -156,7 +156,7 @@ //! [TCP]: net/struct.TcpStream.html //! [The Rust Prelude]: prelude/index.html //! [UDP]: net/struct.UdpSocket.html -//! [`::std::env::args()`]: env/fn.args.html +//! [`::std::env::args`]: env/fn.args.html //! [`Arc`]: sync/struct.Arc.html //! [owned slice]: boxed/index.html //! [`Cell`]: cell/struct.Cell.html diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index 9bead22ef7f..a07972468e6 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -183,7 +183,7 @@ impl TcpStream { /// Sets the read timeout to the timeout specified. /// - /// If the value specified is [`None`], then [`read()`] calls will block + /// If the value specified is [`None`], then [`read`] calls will block /// indefinitely. It is an error to pass the zero `Duration` to this /// method. /// @@ -194,7 +194,7 @@ impl TcpStream { /// error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../std/io/trait.Read.html#tymethod.read + /// [`read`]: ../../std/io/trait.Read.html#tymethod.read /// [`WouldBlock`]: ../../std/io/enum.ErrorKind.html#variant.WouldBlock /// [`TimedOut`]: ../../std/io/enum.ErrorKind.html#variant.TimedOut /// @@ -214,7 +214,7 @@ impl TcpStream { /// Sets the write timeout to the timeout specified. /// - /// If the value specified is [`None`], then [`write()`] calls will block + /// If the value specified is [`None`], then [`write`] calls will block /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// @@ -225,7 +225,7 @@ impl TcpStream { /// an error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`write()`]: ../../std/io/trait.Write.html#tymethod.write + /// [`write`]: ../../std/io/trait.Write.html#tymethod.write /// [`Duration`]: ../../std/time/struct.Duration.html /// [`WouldBlock`]: ../../std/io/enum.ErrorKind.html#variant.WouldBlock /// [`TimedOut`]: ../../std/io/enum.ErrorKind.html#variant.TimedOut @@ -246,14 +246,14 @@ impl TcpStream { /// Returns the read timeout of this socket. /// - /// If the timeout is [`None`], then [`read()`] calls will block indefinitely. + /// If the timeout is [`None`], then [`read`] calls will block indefinitely. /// /// # Note /// /// Some platforms do not provide access to the current timeout. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../std/io/trait.Read.html#tymethod.read + /// [`read`]: ../../std/io/trait.Read.html#tymethod.read /// /// # Examples /// @@ -272,14 +272,14 @@ impl TcpStream { /// Returns the write timeout of this socket. /// - /// If the timeout is [`None`], then [`write()`] calls will block indefinitely. + /// If the timeout is [`None`], then [`write`] calls will block indefinitely. /// /// # Note /// /// Some platforms do not provide access to the current timeout. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`write()`]: ../../std/io/trait.Write.html#tymethod.write + /// [`write`]: ../../std/io/trait.Write.html#tymethod.write /// /// # Examples /// @@ -618,7 +618,7 @@ impl TcpListener { /// Gets the value of the `IP_TTL` option for this socket. /// - /// For more information about this option, see [`set_ttl()`][link]. + /// For more information about this option, see [`set_ttl`][link]. /// /// [link]: #method.set_ttl /// diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs index f452c75d389..1ebce939348 100644 --- a/src/libstd/net/udp.rs +++ b/src/libstd/net/udp.rs @@ -175,7 +175,7 @@ impl UdpSocket { /// Sets the read timeout to the timeout specified. /// - /// If the value specified is [`None`], then [`read()`] calls will block + /// If the value specified is [`None`], then [`read`] calls will block /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// @@ -186,7 +186,7 @@ impl UdpSocket { /// error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../std/io/trait.Read.html#tymethod.read + /// [`read`]: ../../std/io/trait.Read.html#tymethod.read /// [`Duration`]: ../../std/time/struct.Duration.html /// [`WouldBlock`]: ../../std/io/enum.ErrorKind.html#variant.WouldBlock /// [`TimedOut`]: ../../std/io/enum.ErrorKind.html#variant.TimedOut @@ -206,7 +206,7 @@ impl UdpSocket { /// Sets the write timeout to the timeout specified. /// - /// If the value specified is [`None`], then [`write()`] calls will block + /// If the value specified is [`None`], then [`write`] calls will block /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// @@ -217,7 +217,7 @@ impl UdpSocket { /// an error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`write()`]: ../../std/io/trait.Write.html#tymethod.write + /// [`write`]: ../../std/io/trait.Write.html#tymethod.write /// [`Duration`]: ../../std/time/struct.Duration.html /// [`WouldBlock`]: ../../std/io/enum.ErrorKind.html#variant.WouldBlock /// [`TimedOut`]: ../../std/io/enum.ErrorKind.html#variant.TimedOut @@ -237,10 +237,10 @@ impl UdpSocket { /// Returns the read timeout of this socket. /// - /// If the timeout is [`None`], then [`read()`] calls will block indefinitely. + /// If the timeout is [`None`], then [`read`] calls will block indefinitely. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../std/io/trait.Read.html#tymethod.read + /// [`read`]: ../../std/io/trait.Read.html#tymethod.read /// /// # Examples /// @@ -258,10 +258,10 @@ impl UdpSocket { /// Returns the write timeout of this socket. /// - /// If the timeout is [`None`], then [`write()`] calls will block indefinitely. + /// If the timeout is [`None`], then [`write`] calls will block indefinitely. /// /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`write()`]: ../../std/io/trait.Write.html#tymethod.write + /// [`write`]: ../../std/io/trait.Write.html#tymethod.write /// /// # Examples /// @@ -560,10 +560,10 @@ impl UdpSocket { /// Sends data on the socket to the remote address to which it is connected. /// - /// The [`connect()`] method will connect this socket to a remote address. This + /// The [`connect`] method will connect this socket to a remote address. This /// method will fail if the socket is not connected. /// - /// [`connect()`]: #method.connect + /// [`connect`]: #method.connect /// /// # Examples /// diff --git a/src/libstd/panicking.rs b/src/libstd/panicking.rs index 3b5a1cffc7a..6f46a73698f 100644 --- a/src/libstd/panicking.rs +++ b/src/libstd/panicking.rs @@ -160,10 +160,10 @@ pub fn take_hook() -> Box { /// A struct providing information about a panic. /// -/// `PanicInfo` structure is passed to a panic hook set by the [`set_hook()`] +/// `PanicInfo` structure is passed to a panic hook set by the [`set_hook`] /// function. /// -/// [`set_hook()`]: ../../std/panic/fn.set_hook.html +/// [`set_hook`]: ../../std/panic/fn.set_hook.html /// /// # Examples /// @@ -237,9 +237,9 @@ impl<'a> PanicInfo<'a> { /// A struct containing information about the location of a panic. /// -/// This structure is created by the [`location()`] method of [`PanicInfo`]. +/// This structure is created by the [`location`] method of [`PanicInfo`]. /// -/// [`location()`]: ../../std/panic/struct.PanicInfo.html#method.location +/// [`location`]: ../../std/panic/struct.PanicInfo.html#method.location /// [`PanicInfo`]: ../../std/panic/struct.PanicInfo.html /// /// # Examples diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 245a6d945b5..b5d2fe82dea 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1065,13 +1065,13 @@ impl PathBuf { self.inner.push(path); } - /// Truncate `self` to [`self.parent()`]. + /// Truncate `self` to [`self.parent`]. /// - /// Returns false and does nothing if [`self.file_name()`] is `None`. + /// Returns false and does nothing if [`self.file_name`] is `None`. /// Otherwise, returns `true`. /// - /// [`self.parent()`]: struct.PathBuf.html#method.parent - /// [`self.file_name()`]: struct.PathBuf.html#method.file_name + /// [`self.parent`]: struct.PathBuf.html#method.parent + /// [`self.file_name`]: struct.PathBuf.html#method.file_name /// /// # Examples /// @@ -1096,12 +1096,12 @@ impl PathBuf { } } - /// Updates [`self.file_name()`] to `file_name`. + /// Updates [`self.file_name`] to `file_name`. /// - /// If [`self.file_name()`] was [`None`], this is equivalent to pushing + /// If [`self.file_name`] was [`None`], this is equivalent to pushing /// `file_name`. /// - /// [`self.file_name()`]: struct.PathBuf.html#method.file_name + /// [`self.file_name`]: struct.PathBuf.html#method.file_name /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples @@ -1130,15 +1130,15 @@ impl PathBuf { self.push(file_name); } - /// Updates [`self.extension()`] to `extension`. + /// Updates [`self.extension`] to `extension`. /// - /// If [`self.file_name()`] is `None`, does nothing and returns `false`. + /// If [`self.file_name`] is `None`, does nothing and returns `false`. /// - /// Otherwise, returns `true`; if [`self.extension()`] is [`None`], the + /// Otherwise, returns `true`; if [`self.extension`] is [`None`], the /// extension is added; otherwise it is replaced. /// - /// [`self.file_name()`]: struct.PathBuf.html#method.file_name - /// [`self.extension()`]: struct.PathBuf.html#method.extension + /// [`self.file_name`]: struct.PathBuf.html#method.file_name + /// [`self.extension`]: struct.PathBuf.html#method.extension /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples @@ -1733,9 +1733,9 @@ impl Path { iter_after(self.components().rev(), child.components().rev()).is_some() } - /// Extracts the stem (non-extension) portion of [`self.file_name()`]. + /// Extracts the stem (non-extension) portion of [`self.file_name`]. /// - /// [`self.file_name()`]: struct.Path.html#method.file_name + /// [`self.file_name`]: struct.Path.html#method.file_name /// /// The stem is: /// @@ -1760,7 +1760,7 @@ impl Path { self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after)) } - /// Extracts the extension of [`self.file_name()`], if possible. + /// Extracts the extension of [`self.file_name`], if possible. /// /// The extension is: /// @@ -1769,7 +1769,7 @@ impl Path { /// * [`None`], if the file name begins with `.` and has no other `.`s within; /// * Otherwise, the portion of the file name after the final `.` /// - /// [`self.file_name()`]: struct.Path.html#method.file_name + /// [`self.file_name`]: struct.Path.html#method.file_name /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs index f4cd319f064..c71e0b2a703 100644 --- a/src/libstd/prelude/mod.rs +++ b/src/libstd/prelude/mod.rs @@ -60,9 +60,9 @@ //! value. //! * [`std::boxed`]::[`Box`], a way to allocate values on the heap. //! * [`std::borrow`]::[`ToOwned`], The conversion trait that defines -//! [`to_owned()`], the generic method for creating an owned type from a +//! [`to_owned`], the generic method for creating an owned type from a //! borrowed type. -//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines [`clone()`], +//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines [`clone`], //! the method for producing a copy of a value. //! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }. The //! comparison traits, which implement the comparison operators and are often @@ -117,7 +117,7 @@ //! [`ToOwned`]: ../borrow/trait.ToOwned.html //! [`ToString`]: ../string/trait.ToString.html //! [`Vec`]: ../vec/struct.Vec.html -//! [`clone()`]: ../clone/trait.Clone.html#tymethod.clone +//! [`clone`]: ../clone/trait.Clone.html#tymethod.clone //! [`drop`]: ../mem/fn.drop.html //! [`std::borrow`]: ../borrow/index.html //! [`std::boxed`]: ../boxed/index.html @@ -135,7 +135,7 @@ //! [`std::slice`]: ../slice/index.html //! [`std::string`]: ../string/index.html //! [`std::vec`]: ../vec/index.html -//! [`to_owned()`]: ../borrow/trait.ToOwned.html#tymethod.to_owned +//! [`to_owned`]: ../borrow/trait.ToOwned.html#tymethod.to_owned //! [book-closures]: ../../book/closures.html //! [book-dtor]: ../../book/drop.html //! [book-enums]: ../../book/enums.html diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index 11197db98a3..7d6d16f4748 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -420,7 +420,7 @@ mod prim_slice { } /// # Representation /// /// A `&str` is made up of two components: a pointer to some bytes, and a -/// length. You can look at these with the [`.as_ptr()`] and [`len()`] methods: +/// length. You can look at these with the [`.as_ptr`] and [`len`] methods: /// /// ``` /// use std::slice; @@ -447,8 +447,8 @@ mod prim_slice { } /// assert_eq!(s, Ok(story)); /// ``` /// -/// [`.as_ptr()`]: #method.as_ptr -/// [`len()`]: #method.len +/// [`.as_ptr`]: #method.as_ptr +/// [`len`]: #method.len /// /// Note: This example shows the internals of `&str`. `unsafe` should not be /// used to get a string slice under normal circumstances. Use `.as_slice()` diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs index f15e7ff8916..295a49d6a8e 100644 --- a/src/libstd/sync/barrier.rs +++ b/src/libstd/sync/barrier.rs @@ -52,10 +52,10 @@ struct BarrierState { /// A result returned from wait. /// -/// Currently this opaque structure only has one method, [`.is_leader()`]. Only +/// Currently this opaque structure only has one method, [`.is_leader`]. Only /// one thread will receive a result that will return `true` from this function. /// -/// [`.is_leader()`]: #method.is_leader +/// [`.is_leader`]: #method.is_leader /// /// # Examples /// diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs index 68c7e88f67f..7ad9d9ee37c 100644 --- a/src/libstd/sync/condvar.rs +++ b/src/libstd/sync/condvar.rs @@ -150,7 +150,7 @@ impl Condvar { /// /// This function will atomically unlock the mutex specified (represented by /// `guard`) and block the current thread. This means that any calls - /// to [`notify_one()`] or [`notify_all()`] which happen logically after the + /// to [`notify_one`] or [`notify_all`] which happen logically after the /// mutex is unlocked are candidates to wake this thread up. When this /// function call returns, the lock specified will have been re-acquired. /// @@ -167,16 +167,16 @@ impl Condvar { /// /// # Panics /// - /// This function will [`panic!()`] if it is used with more than one mutex + /// This function will [`panic!`] if it is used with more than one mutex /// over time. Each condition variable is dynamically bound to exactly one /// mutex to ensure defined behavior across platforms. If this functionality /// is not desired, then unsafe primitives in `sys` are provided. /// - /// [`notify_one()`]: #method.notify_one - /// [`notify_all()`]: #method.notify_all + /// [`notify_one`]: #method.notify_one + /// [`notify_all`]: #method.notify_all /// [poisoning]: ../sync/struct.Mutex.html#poisoning /// [`Mutex`]: ../sync/struct.Mutex.html - /// [`panic!()`]: ../../std/macro.panic.html + /// [`panic!`]: ../../std/macro.panic.html /// /// # Examples /// @@ -359,11 +359,11 @@ impl Condvar { /// be woken up from its call to [`wait`] or [`wait_timeout`]. Calls to /// `notify_one` are not buffered in any way. /// - /// To wake up all threads, see [`notify_all()`]. + /// To wake up all threads, see [`notify_all`]. /// /// [`wait`]: #method.wait /// [`wait_timeout`]: #method.wait_timeout - /// [`notify_all()`]: #method.notify_all + /// [`notify_all`]: #method.notify_all /// /// # Examples /// @@ -401,9 +401,9 @@ impl Condvar { /// variable are awoken. Calls to `notify_all()` are not buffered in any /// way. /// - /// To wake up only one thread, see [`notify_one()`]. + /// To wake up only one thread, see [`notify_one`]. /// - /// [`notify_one()`]: #method.notify_one + /// [`notify_one`]: #method.notify_one /// /// # Examples /// diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index aeeab170dea..71dd94161c0 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -460,10 +460,10 @@ impl UnsafeFlavor for Receiver { /// All data sent on the sender will become available on the receiver, and no /// send will block the calling thread (this channel has an "infinite buffer"). /// -/// If the [`Receiver`] is disconnected while trying to [`send()`] with the -/// [`Sender`], the [`send()`] method will return an error. +/// If the [`Receiver`] is disconnected while trying to [`send`] with the +/// [`Sender`], the [`send`] method will return an error. /// -/// [`send()`]: ../../../std/sync/mpsc/struct.Sender.html#method.send +/// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send /// [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html /// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html /// @@ -504,13 +504,13 @@ pub fn channel() -> (Sender, Receiver) { /// `bound` specifies the buffer size. When the internal buffer becomes full, /// future sends will *block* waiting for the buffer to open up. Note that a /// buffer size of 0 is valid, in which case this becomes "rendezvous channel" -/// where each [`send()`] will not return until a recv is paired with it. +/// where each [`send`] will not return until a recv is paired with it. /// /// Like asynchronous channels, if the [`Receiver`] is disconnected while -/// trying to [`send()`] with the [`SyncSender`], the [`send()`] method will +/// trying to [`send`] with the [`SyncSender`], the [`send`] method will /// return an error. /// -/// [`send()`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send +/// [`send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send /// [`SyncSender`]: ../../../std/sync/mpsc/struct.SyncSender.html /// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html /// diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 97b84d59218..48d8d34dbe0 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -135,13 +135,13 @@ unsafe impl Sync for Mutex { } /// The data protected by the mutex can be access through this guard via its /// [`Deref`] and [`DerefMut`] implementations. /// -/// This structure is created by the [`lock()`] and [`try_lock()`] methods on +/// This structure is created by the [`lock`] and [`try_lock`] methods on /// [`Mutex`]. /// /// [`Deref`]: ../../std/ops/trait.Deref.html /// [`DerefMut`]: ../../std/ops/trait.DerefMut.html -/// [`lock()`]: struct.Mutex.html#method.lock -/// [`try_lock()`]: struct.Mutex.html#method.try_lock +/// [`lock`]: struct.Mutex.html#method.lock +/// [`try_lock`]: struct.Mutex.html#method.try_lock /// [`Mutex`]: struct.Mutex.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index a3db0adeda0..d26f2f7bb7e 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -78,11 +78,11 @@ unsafe impl Sync for RwLock {} /// RAII structure used to release the shared read access of a lock when /// dropped. /// -/// This structure is created by the [`read()`] and [`try_read()`] methods on +/// This structure is created by the [`read`] and [`try_read`] methods on /// [`RwLock`]. /// -/// [`read()`]: struct.RwLock.html#method.read -/// [`try_read()`]: struct.RwLock.html#method.try_read +/// [`read`]: struct.RwLock.html#method.read +/// [`try_read`]: struct.RwLock.html#method.try_read /// [`RwLock`]: struct.RwLock.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] @@ -96,11 +96,11 @@ impl<'a, T: ?Sized> !marker::Send for RwLockReadGuard<'a, T> {} /// RAII structure used to release the exclusive write access of a lock when /// dropped. /// -/// This structure is created by the [`write()`] and [`try_write()`] methods +/// This structure is created by the [`write`] and [`try_write`] methods /// on [`RwLock`]. /// -/// [`write()`]: struct.RwLock.html#method.write -/// [`try_write()`]: struct.RwLock.html#method.try_write +/// [`write`]: struct.RwLock.html#method.write +/// [`try_write`]: struct.RwLock.html#method.try_write /// [`RwLock`]: struct.RwLock.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index 1ba4a104e51..d5933d316c4 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -375,12 +375,12 @@ impl UnixStream { /// Sets the read timeout for the socket. /// - /// If the provided value is [`None`], then [`read()`] calls will block + /// If the provided value is [`None`], then [`read`] calls will block /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// /// [`None`]: ../../../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../../../std/io/trait.Read.html#tymethod.read + /// [`read`]: ../../../../std/io/trait.Read.html#tymethod.read /// [`Duration`]: ../../../../std/time/struct.Duration.html /// /// # Examples @@ -399,12 +399,12 @@ impl UnixStream { /// Sets the write timeout for the socket. /// - /// If the provided value is [`None`], then [`write()`] calls will block + /// If the provided value is [`None`], then [`write`] calls will block /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// /// [`None`]: ../../../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../../../std/io/trait.Write.html#tymethod.write + /// [`read`]: ../../../../std/io/trait.Write.html#tymethod.write /// [`Duration`]: ../../../../std/time/struct.Duration.html /// /// # Examples @@ -974,12 +974,12 @@ impl UnixDatagram { /// Connects the socket to the specified address. /// - /// The [`send()`] method may be used to send data to the specified address. - /// [`recv()`] and [`recv_from()`] will only receive data from that address. + /// The [`send`] method may be used to send data to the specified address. + /// [`recv`] and [`recv_from`] will only receive data from that address. /// - /// [`send()`]: #method.send - /// [`recv()`]: #method.recv - /// [`recv_from()`]: #method.recv_from + /// [`send`]: #method.send + /// [`recv`]: #method.recv + /// [`recv_from`]: #method.recv_from /// /// # Examples /// @@ -1047,9 +1047,9 @@ impl UnixDatagram { /// Returns the address of this socket's peer. /// - /// The [`connect()`] method will connect the socket to a peer. + /// The [`connect`] method will connect the socket to a peer. /// - /// [`connect()`]: #method.connect + /// [`connect`]: #method.connect /// /// # Examples /// @@ -1178,13 +1178,13 @@ impl UnixDatagram { /// Sets the read timeout for the socket. /// - /// If the provided value is [`None`], then [`recv()`] and [`recv_from()`] calls will + /// If the provided value is [`None`], then [`recv`] and [`recv_from`] calls will /// block indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// /// [`None`]: ../../../../std/option/enum.Option.html#variant.None - /// [`recv()`]: #method.recv - /// [`recv_from()`]: #method.recv_from + /// [`recv`]: #method.recv + /// [`recv_from`]: #method.recv_from /// [`Duration`]: ../../../../std/time/struct.Duration.html /// /// # Examples @@ -1203,13 +1203,13 @@ impl UnixDatagram { /// Sets the write timeout for the socket. /// - /// If the provided value is [`None`], then [`send()`] and [`send_to()`] calls will + /// If the provided value is [`None`], then [`send`] and [`send_to`] calls will /// block indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// /// [`None`]: ../../../../std/option/enum.Option.html#variant.None - /// [`send()`]: #method.send - /// [`send_to()`]: #method.send_to + /// [`send`]: #method.send + /// [`send_to`]: #method.send_to /// [`Duration`]: ../../../../std/time/struct.Duration.html /// /// # Examples diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2bc066d3fea..64c2be25222 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -90,29 +90,29 @@ //! two ways: //! //! * By spawning a new thread, e.g. using the [`thread::spawn`][`spawn`] -//! function, and calling [`thread()`] on the [`JoinHandle`]. -//! * By requesting the current thread, using the [`thread::current()`] function. +//! function, and calling [`thread`] on the [`JoinHandle`]. +//! * By requesting the current thread, using the [`thread::current`] function. //! -//! The [`thread::current()`] function is available even for threads not spawned +//! The [`thread::current`] function is available even for threads not spawned //! by the APIs of this module. //! //! ## Blocking support: park and unpark //! //! Every thread is equipped with some basic low-level blocking support, via the -//! [`thread::park()`][`park()`] function and [`thread::Thread::unpark()`][`unpark()`] -//! method. [`park()`] blocks the current thread, which can then be resumed from -//! another thread by calling the [`unpark()`] method on the blocked thread's handle. +//! [`thread::park`][`park`] function and [`thread::Thread::unpark()`][`unpark`] +//! method. [`park`] blocks the current thread, which can then be resumed from +//! another thread by calling the [`unpark`] method on the blocked thread's handle. //! //! Conceptually, each [`Thread`] handle has an associated token, which is //! initially not present: //! -//! * The [`thread::park()`][`park()`] function blocks the current thread unless or until +//! * The [`thread::park`][`park`] function blocks the current thread unless or until //! the token is available for its thread handle, at which point it atomically //! consumes the token. It may also return *spuriously*, without consuming the -//! token. [`thread::park_timeout()`] does the same, but allows specifying a +//! token. [`thread::park_timeout`] does the same, but allows specifying a //! maximum time to block the thread for. //! -//! * The [`unpark()`] method on a [`Thread`] atomically makes the token available +//! * The [`unpark`] method on a [`Thread`] atomically makes the token available //! if it wasn't already. //! //! In other words, each [`Thread`] acts a bit like a semaphore with initial count @@ -122,7 +122,7 @@ //! The API is typically used by acquiring a handle to the current thread, //! placing that handle in a shared data structure so that other threads can //! find it, and then `park`ing. When some desired condition is met, another -//! thread calls [`unpark()`] on the handle. +//! thread calls [`unpark`] on the handle. //! //! The motivation for this design is twofold: //! @@ -151,18 +151,18 @@ //! [`Arc`]: ../../std/sync/struct.Arc.html //! [`spawn`]: ../../std/thread/fn.spawn.html //! [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html -//! [`thread()`]: ../../std/thread/struct.JoinHandle.html#method.thread +//! [`thread`]: ../../std/thread/struct.JoinHandle.html#method.thread //! [`join`]: ../../std/thread/struct.JoinHandle.html#method.join //! [`Result`]: ../../std/result/enum.Result.html //! [`Ok`]: ../../std/result/enum.Result.html#variant.Ok //! [`Err`]: ../../std/result/enum.Result.html#variant.Err //! [`panic!`]: ../../std/macro.panic.html //! [`Builder`]: ../../std/thread/struct.Builder.html -//! [`thread::current()`]: ../../std/thread/fn.spawn.html +//! [`thread::current`]: ../../std/thread/fn.spawn.html //! [`Thread`]: ../../std/thread/struct.Thread.html -//! [`park()`]: ../../std/thread/fn.park.html -//! [`unpark()`]: ../../std/thread/struct.Thread.html#method.unpark -//! [`thread::park_timeout()`]: ../../std/thread/fn.park_timeout.html +//! [`park`]: ../../std/thread/fn.park.html +//! [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark +//! [`thread::park_timeout`]: ../../std/thread/fn.park_timeout.html //! [`Cell`]: ../cell/struct.Cell.html //! [`RefCell`]: ../cell/struct.RefCell.html //! [`thread_local!`]: ../macro.thread_local.html @@ -547,7 +547,7 @@ pub fn sleep(dur: Duration) { /// Blocks unless or until the current thread's token is made available. /// /// Every thread is equipped with some basic low-level blocking support, via -/// the `park()` function and the [`unpark()`][unpark] method. These can be +/// the `park()` function and the [`unpark`][unpark] method. These can be /// used as a more CPU-efficient implementation of a spinlock. /// /// [unpark]: struct.Thread.html#method.unpark diff --git a/src/libstd_unicode/char.rs b/src/libstd_unicode/char.rs index 4269ce8534b..682eec490bc 100644 --- a/src/libstd_unicode/char.rs +++ b/src/libstd_unicode/char.rs @@ -49,10 +49,10 @@ pub use tables::UNICODE_VERSION; /// Returns an iterator that yields the lowercase equivalent of a `char`. /// -/// This `struct` is created by the [`to_lowercase()`] method on [`char`]. See +/// This `struct` is created by the [`to_lowercase`] method on [`char`]. See /// its documentation for more. /// -/// [`to_lowercase()`]: ../../std/primitive.char.html#method.to_lowercase +/// [`to_lowercase`]: ../../std/primitive.char.html#method.to_lowercase /// [`char`]: ../../std/primitive.char.html #[stable(feature = "rust1", since = "1.0.0")] pub struct ToLowercase(CaseMappingIter); @@ -70,10 +70,10 @@ impl FusedIterator for ToLowercase {} /// Returns an iterator that yields the uppercase equivalent of a `char`. /// -/// This `struct` is created by the [`to_uppercase()`] method on [`char`]. See +/// This `struct` is created by the [`to_uppercase`] method on [`char`]. See /// its documentation for more. /// -/// [`to_uppercase()`]: ../../std/primitive.char.html#method.to_uppercase +/// [`to_uppercase`]: ../../std/primitive.char.html#method.to_uppercase /// [`char`]: ../../std/primitive.char.html #[stable(feature = "rust1", since = "1.0.0")] pub struct ToUppercase(CaseMappingIter); @@ -183,7 +183,7 @@ impl char { /// * `a-z` /// * `A-Z` /// - /// For a more comprehensive understanding of 'digit', see [`is_numeric()`][is_numeric]. + /// For a more comprehensive understanding of 'digit', see [`is_numeric`][is_numeric]. /// /// [is_numeric]: #method.is_numeric /// @@ -465,10 +465,10 @@ impl char { /// Returns the number of 16-bit code units this `char` would need if /// encoded in UTF-16. /// - /// See the documentation for [`len_utf8()`] for more explanation of this + /// See the documentation for [`len_utf8`] for more explanation of this /// concept. This function is a mirror, but for UTF-16 instead of UTF-8. /// - /// [`len_utf8()`]: #method.len_utf8 + /// [`len_utf8`]: #method.len_utf8 /// /// # Examples /// -- cgit 1.4.1-3-g733a5 From 509ef4c496ffafdc635c94e52e4d19b01d0bfb6a Mon Sep 17 00:00:00 2001 From: Simon Sapin Date: Sun, 2 Apr 2017 12:03:54 +0200 Subject: std::thread docs: fix link to current() --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index edf928d6106..18c00e7c5f1 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -158,7 +158,7 @@ //! [`Err`]: ../../std/result/enum.Result.html#variant.Err //! [`panic!`]: ../../std/macro.panic.html //! [`Builder`]: ../../std/thread/struct.Builder.html -//! [`thread::current`]: ../../std/thread/fn.spawn.html +//! [`thread::current`]: ../../std/thread/fn.current.html //! [`Thread`]: ../../std/thread/struct.Thread.html //! [`park`]: ../../std/thread/fn.park.html //! [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark -- cgit 1.4.1-3-g733a5 From 282029526646fc93cd8bc098191c4e110a4c4938 Mon Sep 17 00:00:00 2001 From: "Stephen M. Coakley" Date: Sat, 1 Apr 2017 22:17:59 -0500 Subject: Derive Hash for ThreadId + better example --- src/libstd/thread/mod.rs | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index edf928d6106..21f9757ad11 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -652,8 +652,8 @@ pub fn park_timeout(dur: Duration) { /// A unique identifier for a running thread. /// /// A `ThreadId` is an opaque object that has a unique value for each thread -/// that creates one. `ThreadId`s do not correspond to a thread's system- -/// designated identifier. +/// that creates one. `ThreadId`s are not guaranteed to correspond to a thread's +/// system-designated identifier. /// /// # Examples /// @@ -662,17 +662,15 @@ pub fn park_timeout(dur: Duration) { /// /// use std::thread; /// -/// let handler = thread::Builder::new() -/// .spawn(|| { -/// let thread = thread::current(); -/// let thread_id = thread.id(); -/// }) -/// .unwrap(); +/// let other_thread = thread::spawn(|| { +/// thread::current().id() +/// }); /// -/// handler.join().unwrap(); +/// let other_thread_id = other_thread.join().unwrap(); +/// assert!(thread::current().id() != other_thread_id); /// ``` #[unstable(feature = "thread_id", issue = "21507")] -#[derive(Eq, PartialEq, Copy, Clone)] +#[derive(Clone, Copy, Eq, PartialEq, Hash)] pub struct ThreadId(u64); impl ThreadId { @@ -795,14 +793,12 @@ impl Thread { /// /// use std::thread; /// - /// let handler = thread::Builder::new() - /// .spawn(|| { - /// let thread = thread::current(); - /// println!("thread id: {:?}", thread.id()); - /// }) - /// .unwrap(); + /// let other_thread = thread::spawn(|| { + /// thread::current().id() + /// }); /// - /// handler.join().unwrap(); + /// let other_thread_id = other_thread.join().unwrap(); + /// assert!(thread::current().id() != other_thread_id); /// ``` #[unstable(feature = "thread_id", issue = "21507")] pub fn id(&self) -> ThreadId { -- cgit 1.4.1-3-g733a5 From cd14a323f42cf57695e713a4f4fd00fddc10efd5 Mon Sep 17 00:00:00 2001 From: "Stephen M. Coakley" Date: Tue, 4 Apr 2017 10:44:57 -0500 Subject: Use derived Debug for ThreadId --- src/libstd/thread/mod.rs | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 21f9757ad11..9116f541736 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -670,7 +670,7 @@ pub fn park_timeout(dur: Duration) { /// assert!(thread::current().id() != other_thread_id); /// ``` #[unstable(feature = "thread_id", issue = "21507")] -#[derive(Clone, Copy, Eq, PartialEq, Hash)] +#[derive(Eq, PartialEq, Clone, Copy, Hash, Debug)] pub struct ThreadId(u64); impl ThreadId { @@ -699,13 +699,6 @@ impl ThreadId { } } -#[unstable(feature = "thread_id", issue = "21507")] -impl fmt::Debug for ThreadId { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - f.pad("ThreadId { .. }") - } -} - //////////////////////////////////////////////////////////////////////////////// // Thread //////////////////////////////////////////////////////////////////////////////// -- cgit 1.4.1-3-g733a5 From b4be4758361bf1b03410a523e8672b1c1fa7d385 Mon Sep 17 00:00:00 2001 From: Oliver Middleton Date: Thu, 6 Apr 2017 12:57:40 +0100 Subject: Fix Markdown issues in the docs * Since the switch to pulldown-cmark reference links need a blank line before the URLs. * Reference link references are not case sensitive. * Doc comments need to be indented uniformly otherwise rustdoc gets confused. --- src/libcollections/vec.rs | 2 +- src/libcore/sync/atomic.rs | 5 +++-- src/libstd/fs.rs | 14 ++++++++++++++ src/libstd/io/buffered.rs | 17 +++++++++-------- src/libstd/io/mod.rs | 9 +++++---- src/libstd/net/tcp.rs | 4 ++-- src/libstd/prelude/mod.rs | 12 ++++++------ src/libstd/sys/windows/ext/fs.rs | 2 +- src/libstd/sys/windows/ext/process.rs | 1 + src/libstd/thread/mod.rs | 4 ++-- 10 files changed, 44 insertions(+), 26 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index c258ac2bdea..35ecf411db4 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -1346,7 +1346,7 @@ impl Vec { /// # Examples /// /// ``` - ///# #![feature(vec_remove_item)] + /// # #![feature(vec_remove_item)] /// let mut vec = vec![1, 2, 3, 1]; /// /// vec.remove_item(&1); diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 4e5ddfb541e..2e1058bfc34 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -153,8 +153,9 @@ unsafe impl Sync for AtomicPtr {} /// Rust's memory orderings are [the same as /// LLVM's](http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations). /// -/// For more information see the [nomicon][1]. -/// [1]: ../../../nomicon/atomics.html +/// For more information see the [nomicon]. +/// +/// [nomicon]: ../../../nomicon/atomics.html #[stable(feature = "rust1", since = "1.0.0")] #[derive(Copy, Clone, Debug)] pub enum Ordering { diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 1b00eb95de2..6b1267d89b6 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -1176,6 +1176,7 @@ impl AsInner for DirEntry { /// This function currently corresponds to the `unlink` function on Unix /// and the `DeleteFile` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1212,6 +1213,7 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// This function currently corresponds to the `stat` function on Unix /// and the `GetFileAttributesEx` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1245,6 +1247,7 @@ pub fn metadata>(path: P) -> io::Result { /// This function currently corresponds to the `lstat` function on Unix /// and the `GetFileAttributesEx` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1287,6 +1290,7 @@ pub fn symlink_metadata>(path: P) -> io::Result { /// on Windows, `from` can be anything, but `to` must *not* be a directory. /// /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1330,6 +1334,7 @@ pub fn rename, Q: AsRef>(from: P, to: Q) -> io::Result<()> /// `O_CLOEXEC` is set for returned file descriptors. /// On Windows, this function currently corresponds to `CopyFileEx`. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1366,6 +1371,7 @@ pub fn copy, Q: AsRef>(from: P, to: Q) -> io::Result { /// This function currently corresponds to the `link` function on Unix /// and the `CreateHardLink` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1424,6 +1430,7 @@ pub fn soft_link, Q: AsRef>(src: P, dst: Q) -> io::Result<( /// and the `CreateFile` function with `FILE_FLAG_OPEN_REPARSE_POINT` and /// `FILE_FLAG_BACKUP_SEMANTICS` flags on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1457,6 +1464,7 @@ pub fn read_link>(path: P) -> io::Result { /// This function currently corresponds to the `realpath` function on Unix /// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1489,6 +1497,7 @@ pub fn canonicalize>(path: P) -> io::Result { /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1522,6 +1531,7 @@ pub fn create_dir>(path: P) -> io::Result<()> { /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1562,6 +1572,7 @@ pub fn create_dir_all>(path: P) -> io::Result<()> { /// This function currently corresponds to the `rmdir` function on Unix /// and the `RemoveDirectory` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1599,6 +1610,7 @@ pub fn remove_dir>(path: P) -> io::Result<()> { /// and the `FindFirstFile`, `GetFileAttributesEx`, `DeleteFile`, and `RemoveDirectory` functions /// on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1633,6 +1645,7 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// This function currently corresponds to the `opendir` function on Unix /// and the `FindFirstFile` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors @@ -1679,6 +1692,7 @@ pub fn read_dir>(path: P) -> io::Result { /// This function currently corresponds to the `chmod` function on Unix /// and the `SetFileAttributes` function on Windows. /// Note that, this [may change in the future][changes]. +/// /// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs index f98a3a87b01..3b82412716e 100644 --- a/src/libstd/io/buffered.rs +++ b/src/libstd/io/buffered.rs @@ -21,12 +21,12 @@ use memchr; /// The `BufReader` struct adds buffering to any reader. /// /// It can be excessively inefficient to work directly with a [`Read`] instance. -/// For example, every call to [`read`] on [`TcpStream`] results in a system call. -/// A `BufReader` performs large, infrequent reads on the underlying [`Read`] -/// and maintains an in-memory buffer of the results. +/// For example, every call to [`read`][`TcpStream::read`] on [`TcpStream`] +/// results in a system call. A `BufReader` performs large, infrequent reads on +/// the underlying [`Read`] and maintains an in-memory buffer of the results. /// /// [`Read`]: ../../std/io/trait.Read.html -/// [`read`]: ../../std/net/struct.TcpStream.html#method.read +/// [`TcpStream::read`]: ../../std/net/struct.TcpStream.html#method.read /// [`TcpStream`]: ../../std/net/struct.TcpStream.html /// /// # Examples @@ -261,9 +261,10 @@ impl Seek for BufReader { /// Wraps a writer and buffers its output. /// /// It can be excessively inefficient to work directly with something that -/// implements [`Write`]. For example, every call to [`write`] on [`TcpStream`] -/// results in a system call. A `BufWriter` keeps an in-memory buffer of data -/// and writes it to an underlying writer in large, infrequent batches. +/// implements [`Write`]. For example, every call to +/// [`write`][`Tcpstream::write`] on [`TcpStream`] results in a system call. A +/// `BufWriter` keeps an in-memory buffer of data and writes it to an underlying +/// writer in large, infrequent batches. /// /// The buffer will be written out when the writer is dropped. /// @@ -303,7 +304,7 @@ impl Seek for BufReader { /// the `stream` is dropped. /// /// [`Write`]: ../../std/io/trait.Write.html -/// [`write`]: ../../std/net/struct.TcpStream.html#method.write +/// [`Tcpstream::write`]: ../../std/net/struct.TcpStream.html#method.write /// [`TcpStream`]: ../../std/net/struct.TcpStream.html #[stable(feature = "rust1", since = "1.0.0")] pub struct BufWriter { diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 8ebc5c0a8fe..cd096c115ba 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -21,7 +21,8 @@ //! of other types, and you can implement them for your types too. As such, //! you'll see a few different types of I/O throughout the documentation in //! this module: [`File`]s, [`TcpStream`]s, and sometimes even [`Vec`]s. For -//! example, [`Read`] adds a [`read`] method, which we can use on `File`s: +//! example, [`Read`] adds a [`read`][`Read::read`] method, which we can use on +//! `File`s: //! //! ``` //! use std::io; @@ -106,7 +107,7 @@ //! ``` //! //! [`BufWriter`] doesn't add any new ways of writing; it just buffers every call -//! to [`write`]: +//! to [`write`][`Write::write`]: //! //! ``` //! use std::io; @@ -257,13 +258,13 @@ //! [`Vec`]: ../vec/struct.Vec.html //! [`BufReader`]: struct.BufReader.html //! [`BufWriter`]: struct.BufWriter.html -//! [`write`]: trait.Write.html#tymethod.write +//! [`Write::write`]: trait.Write.html#tymethod.write //! [`io::stdout`]: fn.stdout.html //! [`println!`]: ../macro.println.html //! [`Lines`]: struct.Lines.html //! [`io::Result`]: type.Result.html //! [`?` operator]: ../../book/syntax-index.html -//! [`read`]: trait.Read.html#tymethod.read +//! [`Read::read`]: trait.Read.html#tymethod.read #![stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index cf119720e5a..bc315d54100 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -58,7 +58,7 @@ pub struct TcpStream(net_imp::TcpStream); /// /// After creating a `TcpListener` by [`bind`]ing it to a socket address, it listens /// for incoming TCP connections. These can be accepted by calling [`accept`] or by -/// iterating over the [`Incoming`] iterator returned by [`incoming`]. +/// iterating over the [`Incoming`] iterator returned by [`incoming`][`TcpListener::incoming`]. /// /// The socket will be closed when the value is dropped. /// @@ -68,7 +68,7 @@ pub struct TcpStream(net_imp::TcpStream); /// [`bind`]: #method.bind /// [IETF RFC 793]: https://tools.ietf.org/html/rfc793 /// [`Incoming`]: ../../std/net/struct.Incoming.html -/// [`incoming`]: #method.incoming +/// [`TcpListener::incoming`]: #method.incoming /// /// # Examples /// diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs index c71e0b2a703..86e661d7948 100644 --- a/src/libstd/prelude/mod.rs +++ b/src/libstd/prelude/mod.rs @@ -56,14 +56,14 @@ //! traits indicate fundamental properties of types. //! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}. Various //! operations for both destructors and overloading `()`. -//! * [`std::mem`]::[`drop`], a convenience function for explicitly dropping a -//! value. +//! * [`std::mem`]::[`drop`][`mem::drop`], a convenience function for explicitly +//! dropping a value. //! * [`std::boxed`]::[`Box`], a way to allocate values on the heap. //! * [`std::borrow`]::[`ToOwned`], The conversion trait that defines //! [`to_owned`], the generic method for creating an owned type from a //! borrowed type. -//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines [`clone`], -//! the method for producing a copy of a value. +//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines +//! [`clone`][`Clone::clone`], the method for producing a copy of a value. //! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }. The //! comparison traits, which implement the comparison operators and are often //! seen in trait bounds. @@ -117,8 +117,8 @@ //! [`ToOwned`]: ../borrow/trait.ToOwned.html //! [`ToString`]: ../string/trait.ToString.html //! [`Vec`]: ../vec/struct.Vec.html -//! [`clone`]: ../clone/trait.Clone.html#tymethod.clone -//! [`drop`]: ../mem/fn.drop.html +//! [`Clone::clone`]: ../clone/trait.Clone.html#tymethod.clone +//! [`mem::drop`]: ../mem/fn.drop.html //! [`std::borrow`]: ../borrow/index.html //! [`std::boxed`]: ../boxed/index.html //! [`std::clone`]: ../clone/index.html diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index c63dd8a47ca..d6e2fed56be 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -144,7 +144,7 @@ pub trait OpenOptionsExt { /// `CreateFile`). /// /// If a _new_ file is created because it does not yet exist and - ///`.create(true)` or `.create_new(true)` are specified, the new file is + /// `.create(true)` or `.create_new(true)` are specified, the new file is /// given the attributes declared with `.attributes()`. /// /// If an _existing_ file is opened with `.create(true).truncate(true)`, its diff --git a/src/libstd/sys/windows/ext/process.rs b/src/libstd/sys/windows/ext/process.rs index 1419a4af427..759f055c4b1 100644 --- a/src/libstd/sys/windows/ext/process.rs +++ b/src/libstd/sys/windows/ext/process.rs @@ -104,6 +104,7 @@ pub trait CommandExt { /// Sets the [process creation flags][1] to be passed to `CreateProcess`. /// /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`. + /// /// [1]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms684863(v=vs.85).aspx #[stable(feature = "windows_process_extensions", since = "1.16.0")] fn creation_flags(&mut self, flags: u32) -> &mut process::Command; diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 18c00e7c5f1..7ab6b82ada3 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -90,7 +90,7 @@ //! two ways: //! //! * By spawning a new thread, e.g. using the [`thread::spawn`][`spawn`] -//! function, and calling [`thread`] on the [`JoinHandle`]. +//! function, and calling [`thread`][`JoinHandle::thread`] on the [`JoinHandle`]. //! * By requesting the current thread, using the [`thread::current`] function. //! //! The [`thread::current`] function is available even for threads not spawned @@ -151,7 +151,7 @@ //! [`Arc`]: ../../std/sync/struct.Arc.html //! [`spawn`]: ../../std/thread/fn.spawn.html //! [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html -//! [`thread`]: ../../std/thread/struct.JoinHandle.html#method.thread +//! [`JoinHandle::thread`]: ../../std/thread/struct.JoinHandle.html#method.thread //! [`join`]: ../../std/thread/struct.JoinHandle.html#method.join //! [`Result`]: ../../std/result/enum.Result.html //! [`Ok`]: ../../std/result/enum.Result.html#variant.Ok -- cgit 1.4.1-3-g733a5 From 08514b4376eda86f2c05d91334333ebf8caad064 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Tue, 25 Apr 2017 17:22:34 -0500 Subject: rewrote the thread struct docs --- src/libstd/thread/mod.rs | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index e37cc7e963e..98452a396aa 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -713,22 +713,27 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread. +/// A handle to a thread, its just an abstract reference and as such +/// it can be used to identify a thread (by name, for example). In most +/// usage cases, this struct is not used directly. /// /// # Examples /// /// ``` /// use std::thread; /// -/// let handler = thread::Builder::new() -/// .name("foo".into()) +/// for i in 0..5 { +/// let thread_name = format!("thread_{}", i); +/// thread::Builder::new() +/// .name(thread_name) // Now you can identify which thread panicked +/// // thanks to the handle's name /// .spawn(|| { -/// let thread = thread::current(); -/// println!("thread name: {}", thread.name().unwrap()); +/// if i == 3 { +/// panic!("I'm scared!!!"); +/// } /// }) /// .unwrap(); -/// -/// handler.join().unwrap(); +/// } /// ``` pub struct Thread { inner: Arc, -- cgit 1.4.1-3-g733a5 From bdb6bb9684e5cc874d69d6cd65be3d9fb1e64401 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Wed, 26 Apr 2017 00:57:59 -0500 Subject: added move --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 98452a396aa..aa7ef2da0ae 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -727,7 +727,7 @@ struct Inner { /// thread::Builder::new() /// .name(thread_name) // Now you can identify which thread panicked /// // thanks to the handle's name -/// .spawn(|| { +/// .spawn(move || { /// if i == 3 { /// panic!("I'm scared!!!"); /// } -- cgit 1.4.1-3-g733a5 From cf521211a13ccb7e8ea25af97d0efc3abe6d9070 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Wed, 26 Apr 2017 11:54:17 -0500 Subject: restructured docs for thread and added links --- src/libstd/thread/mod.rs | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index aa7ef2da0ae..4e49c485f10 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -713,28 +713,34 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread, its just an abstract reference and as such -/// it can be used to identify a thread (by name, for example). In most -/// usage cases, this struct is not used directly. +/// A handle to a thread. +/// +/// You can use it to identify a thread (by name, for example). Most of the +/// time, there is no need to directly create a `Thread` struct using the +/// constructor, instead you should use a function like `spawn` to create +/// new threads, see the docs of [`Builder`] and [`spawn`] for more. /// /// # Examples /// /// ``` -/// use std::thread; +/// use std::thread::Builder; /// /// for i in 0..5 { /// let thread_name = format!("thread_{}", i); -/// thread::Builder::new() -/// .name(thread_name) // Now you can identify which thread panicked -/// // thanks to the handle's name -/// .spawn(move || { -/// if i == 3 { -/// panic!("I'm scared!!!"); -/// } -/// }) -/// .unwrap(); +/// Builder::new() +/// .name(thread_name) // Now you can identify which thread panicked +/// // thanks to the handle's name +/// .spawn(move || { +/// if i == 3 { +/// panic!("I'm scared!!!"); +/// } +/// }) +/// .unwrap(); /// } /// ``` +/// [`Builder`]: ../../std/thread/struct.Builder.html +/// [`spawn`]: ../../std/thread/fn.spawn.html + pub struct Thread { inner: Arc, } -- cgit 1.4.1-3-g733a5 From a3998ad6e59a6a833e27e9ea6691d3ecd1e877a1 Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Thu, 4 May 2017 11:11:14 +0200 Subject: Join method returns a thread::Result --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4e49c485f10..7fc43a341a8 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -66,7 +66,7 @@ //! let res = child.join(); //! ``` //! -//! The [`join`] method returns a [`Result`] containing [`Ok`] of the final +//! The [`join`] method returns a [`thread::Result`] containing [`Ok`] of the final //! value produced by the child thread, or [`Err`] of the value given to //! a call to [`panic!`] if the child panicked. //! -- cgit 1.4.1-3-g733a5 From 3a07155a9df03ced8c077990a3af0eb7b40d5c8b Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Thu, 4 May 2017 11:33:26 +0200 Subject: create link to Result --- src/libstd/thread/mod.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 7fc43a341a8..719b50d1196 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -159,6 +159,7 @@ //! [`panic!`]: ../../std/macro.panic.html //! [`Builder`]: ../../std/thread/struct.Builder.html //! [`thread::current`]: ../../std/thread/fn.current.html +//! [`thread::Result`]: ../../std/thread/struct.Result.html //! [`Thread`]: ../../std/thread/struct.Thread.html //! [`park`]: ../../std/thread/fn.park.html //! [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark -- cgit 1.4.1-3-g733a5 From 93e179a8c132f6aa9790b198cdcdd441424b4a84 Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Thu, 4 May 2017 14:04:03 +0200 Subject: Update mod.rs --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 719b50d1196..8e7eaa77cd7 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -159,7 +159,7 @@ //! [`panic!`]: ../../std/macro.panic.html //! [`Builder`]: ../../std/thread/struct.Builder.html //! [`thread::current`]: ../../std/thread/fn.current.html -//! [`thread::Result`]: ../../std/thread/struct.Result.html +//! [`thread::Result`]: ../../std/thread/type.Result.html //! [`Thread`]: ../../std/thread/struct.Thread.html //! [`park`]: ../../std/thread/fn.park.html //! [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark -- cgit 1.4.1-3-g733a5 From 68bb5414624d80bec29883c324eb239be73e749d Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Fri, 5 May 2017 12:02:02 +0200 Subject: Add an example to std::thread::Result type --- src/libstd/thread/mod.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 8e7eaa77cd7..2ce5a7262d9 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -863,9 +863,31 @@ impl fmt::Debug for Thread { // JoinHandle //////////////////////////////////////////////////////////////////////////////// +/// A specialized [`Result`] type for threads. +/// /// Indicates the manner in which a thread exited. /// /// A thread that completes without panicking is considered to exit successfully. +/// +/// # Examples +/// +/// ```no_run +/// use std::thread; +/// use std::fs; +/// +/// fn copy_in_thread() -> thread::Result<()> { +/// thread::spawn(move || { fs::copy("foo.txt", "bar.txt").unwrap(); }).join() +/// } +/// +/// fn main() { +/// match copy_in_thread() { +/// Ok(_) => println!("this is fine"), +/// Err(_) => println!("thread panicked"), +/// } +/// } +/// ``` +/// +/// [`Result`]: ../../std/result/enum.Result.html #[stable(feature = "rust1", since = "1.0.0")] pub type Result = ::result::Result>; -- cgit 1.4.1-3-g733a5 From 71aaab1c360f9910238258fb4025b3bd5d5c0645 Mon Sep 17 00:00:00 2001 From: Raphaël Huchet Date: Fri, 5 May 2017 12:07:14 +0200 Subject: Update mod.rs --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2ce5a7262d9..279fe0376d2 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -864,7 +864,7 @@ impl fmt::Debug for Thread { //////////////////////////////////////////////////////////////////////////////// /// A specialized [`Result`] type for threads. -/// +/// /// Indicates the manner in which a thread exited. /// /// A thread that completes without panicking is considered to exit successfully. -- cgit 1.4.1-3-g733a5 From 94e4b459efa3e75c190aeb50da88a02661b3d214 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Fri, 5 May 2017 07:02:48 -0700 Subject: std: Prevent deadlocks in doctests on Windows Windows historically has problems with threads panicking and the main thread exiting at the same time, typically causing deadlocks. In the past (#25824) we've joined on threads but this just prevents running the test for now to avoid tampering with the example. --- src/libstd/thread/mod.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 8e7eaa77cd7..9cded2ab289 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -723,7 +723,9 @@ struct Inner { /// /// # Examples /// -/// ``` +/// ```no_run +/// # // Note that this example isn't executed by default because it causes +/// # // deadlocks on Windows unfortunately (see #25824) /// use std::thread::Builder; /// /// for i in 0..5 { -- cgit 1.4.1-3-g733a5 From 061b56bd5ca2d3a49bebdd6a174995e1b3ec6a5b Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 13:47:39 +0200 Subject: Add a link to `park` in the `park_timeout` doc. Part of #29378 --- src/libstd/thread/mod.rs | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 8e7eaa77cd7..dbc8562ea39 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -585,9 +585,9 @@ pub fn park() { /// Blocks unless or until the current thread's token is made available or /// the specified duration has been reached (may wake spuriously). /// -/// The semantics of this function are equivalent to `park()` except that the -/// thread will be blocked for roughly no longer than `ms`. This method -/// should not be used for precise timing due to anomalies such as +/// The semantics of this function are equivalent to [`park()`][[park] except +/// that the thread will be blocked for roughly no longer than `dur`. This +/// method should not be used for precise timing due to anomalies such as /// preemption or platform differences that may not cause the maximum /// amount of time waited to be precisely `ms` long. /// @@ -595,6 +595,7 @@ pub fn park() { /// /// [thread]: index.html /// [park_timeout]: fn.park_timeout.html +/// [park]: fn.park.html #[stable(feature = "rust1", since = "1.0.0")] #[rustc_deprecated(since = "1.6.0", reason = "replaced by `std::thread::park_timeout`")] pub fn park_timeout_ms(ms: u32) { @@ -604,9 +605,9 @@ pub fn park_timeout_ms(ms: u32) { /// Blocks unless or until the current thread's token is made available or /// the specified duration has been reached (may wake spuriously). /// -/// The semantics of this function are equivalent to `park()` except that the -/// thread will be blocked for roughly no longer than `dur`. This method -/// should not be used for precise timing due to anomalies such as +/// The semantics of this function are equivalent to [`park()`][[park] except +/// that the thread will be blocked for roughly no longer than `dur`. This +/// method should not be used for precise timing due to anomalies such as /// preemption or platform differences that may not cause the maximum /// amount of time waited to be precisely `dur` long. /// @@ -635,6 +636,8 @@ pub fn park_timeout_ms(ms: u32) { /// park_timeout(timeout); /// } /// ``` +/// +/// [park]: fn.park.html #[stable(feature = "park_timeout", since = "1.4.0")] pub fn park_timeout(dur: Duration) { let thread = current(); -- cgit 1.4.1-3-g733a5 From c158962169e3cf0686cb70652282bcdf20772926 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 13:50:23 +0200 Subject: Add link to the module doc in `park_timeout`. Part of #29378 --- src/libstd/thread/mod.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index dbc8562ea39..1857f81a339 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -611,7 +611,7 @@ pub fn park_timeout_ms(ms: u32) { /// preemption or platform differences that may not cause the maximum /// amount of time waited to be precisely `dur` long. /// -/// See the module doc for more detail. +/// See the [module doc][thread] for more detail. /// /// # Platform behavior /// @@ -637,6 +637,7 @@ pub fn park_timeout_ms(ms: u32) { /// } /// ``` /// +/// [thread]: index.html /// [park]: fn.park.html #[stable(feature = "park_timeout", since = "1.4.0")] pub fn park_timeout(dur: Duration) { -- cgit 1.4.1-3-g733a5 From d9628f9389319c1075d4a54a0a490226539cea81 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 13:54:06 +0200 Subject: Add `park` info to `unpark`. - Adds an explanantion of what `park` does in the `unpark` documentation. - Adds a link to the module doc. --- src/libstd/thread/mod.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 1857f81a339..bdf7b1134bf 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -768,7 +768,11 @@ impl Thread { /// Atomically makes the handle's token available if it is not already. /// - /// See the module doc for more detail. + /// Every thread is equipped with some basic low-level blocking support, via + /// the [`park()`][park] function and the `unpark` method. These can be + /// used as a more CPU-efficient implementation of a spinlock. + /// + /// See the [module doc][thread] for more detail. /// /// # Examples /// @@ -784,6 +788,9 @@ impl Thread { /// /// handler.join().unwrap(); /// ``` + /// + /// [thread]: index.html + /// [park]: fn.park.html #[stable(feature = "rust1", since = "1.0.0")] pub fn unpark(&self) { let mut guard = self.inner.lock.lock().unwrap(); -- cgit 1.4.1-3-g733a5 From 5573c4709cba7b3d5dc15c47239d1b1f32af4753 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 16:01:47 +0200 Subject: Better example for `thread::unpark`. Part of #29378 --- src/libstd/thread/mod.rs | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index bdf7b1134bf..94a2c91858e 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -769,7 +769,7 @@ impl Thread { /// Atomically makes the handle's token available if it is not already. /// /// Every thread is equipped with some basic low-level blocking support, via - /// the [`park()`][park] function and the `unpark` method. These can be + /// the [`park()`][park] function and the `unpark()` method. These can be /// used as a more CPU-efficient implementation of a spinlock. /// /// See the [module doc][thread] for more detail. @@ -779,14 +779,21 @@ impl Thread { /// ``` /// use std::thread; /// - /// let handler = thread::Builder::new() + /// let parked_thread = thread::Builder::new() /// .spawn(|| { - /// let thread = thread::current(); - /// thread.unpark(); + /// println!("Parking thread"); + /// thread::park(); + /// println!("Thread unparked"); /// }) /// .unwrap(); /// - /// handler.join().unwrap(); + /// // Let some time pass for the thread to be spawned. + /// thread::sleep(Duration::from_millis(10)); + /// + /// println!("Unpark the thread"); + /// parked_thread.thread().unpark(); + /// + /// parked_thread.join().unwrap(); /// ``` /// /// [thread]: index.html -- cgit 1.4.1-3-g733a5 From c0d475ad7b44c153b4999709ff08a9275160ea1c Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 16:22:13 +0200 Subject: fix typo --- src/libstd/thread/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 94a2c91858e..9c15857edf6 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -585,7 +585,7 @@ pub fn park() { /// Blocks unless or until the current thread's token is made available or /// the specified duration has been reached (may wake spuriously). /// -/// The semantics of this function are equivalent to [`park()`][[park] except +/// The semantics of this function are equivalent to [`park()`][park] except /// that the thread will be blocked for roughly no longer than `dur`. This /// method should not be used for precise timing due to anomalies such as /// preemption or platform differences that may not cause the maximum @@ -605,7 +605,7 @@ pub fn park_timeout_ms(ms: u32) { /// Blocks unless or until the current thread's token is made available or /// the specified duration has been reached (may wake spuriously). /// -/// The semantics of this function are equivalent to [`park()`][[park] except +/// The semantics of this function are equivalent to [`park()`][park] except /// that the thread will be blocked for roughly no longer than `dur`. This /// method should not be used for precise timing due to anomalies such as /// preemption or platform differences that may not cause the maximum -- cgit 1.4.1-3-g733a5 From 12efc9d0faefdd18e715690c7ae30908d92b8fc5 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 16:49:18 +0200 Subject: Improve `thread::panicking` documentaion. Part of #29378 --- src/libstd/thread/mod.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4cbcfdbc2d7..04cd28df445 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -458,6 +458,16 @@ pub fn yield_now() { /// Determines whether the current thread is unwinding because of panic. /// +/// A common use of this feature is to poison shared resources when writing +/// unsafe code, by checking `panicking` when the `drop` is called. +/// +/// This is usually not needed when writing safe code, as [`Mutex`es][Mutex] +/// already poison themselves when a thread panics while holding the lock. +/// +/// This can also be used in multithreaded applications, in order to send a +/// message to other threads warning that a thread has panicked (e.g. for +/// monitoring purposes). +/// /// # Examples /// /// ```should_panic @@ -486,6 +496,8 @@ pub fn yield_now() { /// panic!() /// } /// ``` +/// +/// [Mutex]: ../../std/sync/struct.Mutex.html #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn panicking() -> bool { -- cgit 1.4.1-3-g733a5 From fa0cdaa63f575c81c7cc87239f7dfcc677362c78 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 18:55:20 +0200 Subject: Inline `thread::park` documentation. Part of #29378 - Moves the module documentation into `park`. - Add the same example as the one from `unpark` to `park`. --- src/libstd/thread/mod.rs | 114 ++++++++++++++++++++++++++--------------------- 1 file changed, 62 insertions(+), 52 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 9c15857edf6..5373bf273d4 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -96,41 +96,6 @@ //! The [`thread::current`] function is available even for threads not spawned //! by the APIs of this module. //! -//! ## Blocking support: park and unpark -//! -//! Every thread is equipped with some basic low-level blocking support, via the -//! [`thread::park`][`park`] function and [`thread::Thread::unpark()`][`unpark`] -//! method. [`park`] blocks the current thread, which can then be resumed from -//! another thread by calling the [`unpark`] method on the blocked thread's handle. -//! -//! Conceptually, each [`Thread`] handle has an associated token, which is -//! initially not present: -//! -//! * The [`thread::park`][`park`] function blocks the current thread unless or until -//! the token is available for its thread handle, at which point it atomically -//! consumes the token. It may also return *spuriously*, without consuming the -//! token. [`thread::park_timeout`] does the same, but allows specifying a -//! maximum time to block the thread for. -//! -//! * The [`unpark`] method on a [`Thread`] atomically makes the token available -//! if it wasn't already. -//! -//! In other words, each [`Thread`] acts a bit like a semaphore with initial count -//! 0, except that the semaphore is *saturating* (the count cannot go above 1), -//! and can return spuriously. -//! -//! The API is typically used by acquiring a handle to the current thread, -//! placing that handle in a shared data structure so that other threads can -//! find it, and then `park`ing. When some desired condition is met, another -//! thread calls [`unpark`] on the handle. -//! -//! The motivation for this design is twofold: -//! -//! * It avoids the need to allocate mutexes and condvars when building new -//! synchronization primitives; the threads already provide basic blocking/signaling. -//! -//! * It can be implemented very efficiently on many platforms. -//! //! ## Thread-local storage //! //! This module also provides an implementation of thread-local storage for Rust @@ -547,23 +512,71 @@ pub fn sleep(dur: Duration) { /// Blocks unless or until the current thread's token is made available. /// -/// Every thread is equipped with some basic low-level blocking support, via -/// the `park()` function and the [`unpark`][unpark] method. These can be -/// used as a more CPU-efficient implementation of a spinlock. +/// A call to `park` does not guarantee that the thread will remain parked +/// forever, and callers should be prepared for this possibility. +/// +/// # park and unpark +/// +/// Every thread is equipped with some basic low-level blocking support, via the +/// [`thread::park`][`park`] function and [`thread::Thread::unpark()`][`unpark`] +/// method. [`park`] blocks the current thread, which can then be resumed from +/// another thread by calling the [`unpark`] method on the blocked thread's +/// handle. +/// +/// Conceptually, each [`Thread`] handle has an associated token, which is +/// initially not present: +/// +/// * The [`thread::park`][`park`] function blocks the current thread unless or +/// until the token is available for its thread handle, at which point it +/// atomically consumes the token. It may also return *spuriously*, without +/// consuming the token. [`thread::park_timeout`] does the same, but allows +/// specifying a maximum time to block the thread for. +/// +/// * The [`unpark`] method on a [`Thread`] atomically makes the token available +/// if it wasn't already. /// -/// [unpark]: struct.Thread.html#method.unpark +/// In other words, each [`Thread`] acts a bit like a spinlock that can be +/// locked and unlocked using `park` and `unpark`. /// /// The API is typically used by acquiring a handle to the current thread, /// placing that handle in a shared data structure so that other threads can -/// find it, and then parking (in a loop with a check for the token actually -/// being acquired). +/// find it, and then `park`ing. When some desired condition is met, another +/// thread calls [`unpark`] on the handle. /// -/// A call to `park` does not guarantee that the thread will remain parked -/// forever, and callers should be prepared for this possibility. +/// The motivation for this design is twofold: +/// +/// * It avoids the need to allocate mutexes and condvars when building new +/// synchronization primitives; the threads already provide basic +/// blocking/signaling. /// -/// See the [module documentation][thread] for more detail. +/// * It can be implemented very efficiently on many platforms. +/// +/// # Examples /// -/// [thread]: index.html +/// ``` +/// use std::thread; +/// +/// let parked_thread = thread::Builder::new() +/// .spawn(|| { +/// println!("Parking thread"); +/// thread::park(); +/// println!("Thread unparked"); +/// }) +/// .unwrap(); +/// +/// // Let some time pass for the thread to be spawned. +/// thread::sleep(Duration::from_millis(10)); +/// +/// println!("Unpark the thread"); +/// parked_thread.thread().unpark(); +/// +/// parked_thread.join().unwrap(); +/// ``` +/// +/// [`Thread`]: ../../std/thread/struct.Thread.html +/// [`park`]: ../../std/thread/fn.park.html +/// [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark +/// [`thread::park_timeout`]: ../../std/thread/fn.park_timeout.html // // The implementation currently uses the trivial strategy of a Mutex+Condvar // with wakeup flag, which does not actually allow spurious wakeups. In the @@ -591,11 +604,10 @@ pub fn park() { /// preemption or platform differences that may not cause the maximum /// amount of time waited to be precisely `ms` long. /// -/// See the [module documentation][thread] for more detail. +/// See the [park documentation][park] for more detail. /// -/// [thread]: index.html /// [park_timeout]: fn.park_timeout.html -/// [park]: fn.park.html +/// [park]: ../../std/thread/fn.park.html #[stable(feature = "rust1", since = "1.0.0")] #[rustc_deprecated(since = "1.6.0", reason = "replaced by `std::thread::park_timeout`")] pub fn park_timeout_ms(ms: u32) { @@ -611,7 +623,7 @@ pub fn park_timeout_ms(ms: u32) { /// preemption or platform differences that may not cause the maximum /// amount of time waited to be precisely `dur` long. /// -/// See the [module doc][thread] for more detail. +/// See the [park dococumentation][park] for more details. /// /// # Platform behavior /// @@ -637,7 +649,6 @@ pub fn park_timeout_ms(ms: u32) { /// } /// ``` /// -/// [thread]: index.html /// [park]: fn.park.html #[stable(feature = "park_timeout", since = "1.4.0")] pub fn park_timeout(dur: Duration) { @@ -772,7 +783,7 @@ impl Thread { /// the [`park()`][park] function and the `unpark()` method. These can be /// used as a more CPU-efficient implementation of a spinlock. /// - /// See the [module doc][thread] for more detail. + /// See the [park documentation][park] for more details. /// /// # Examples /// @@ -796,7 +807,6 @@ impl Thread { /// parked_thread.join().unwrap(); /// ``` /// - /// [thread]: index.html /// [park]: fn.park.html #[stable(feature = "rust1", since = "1.0.0")] pub fn unpark(&self) { -- cgit 1.4.1-3-g733a5 From ddb9e50b45b9762e09d341cce8547055cbee4840 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 18:42:36 +0200 Subject: Add stack size doc to `thread::spawn`. Part of #29378 --- src/libstd/thread/mod.rs | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4cbcfdbc2d7..2f7a17af779 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -244,6 +244,11 @@ impl Builder { /// Generates the base configuration for spawning a thread, from which /// configuration methods can be chained. /// + /// If the [`stack_size`][stack_size] field is not specified, the stack size + /// will be the `RUST_MIN_STACK` environment variable, if it is + /// not specified either, a sensible default size will be set (2MB as + /// of the writting of this doc). + /// /// # Examples /// /// ``` @@ -259,6 +264,8 @@ impl Builder { /// /// handler.join().unwrap(); /// ``` + /// + /// [stack_size]: ../../std/thread/struct.Builder.html#method.stack_size #[stable(feature = "rust1", since = "1.0.0")] pub fn new() -> Builder { Builder { -- cgit 1.4.1-3-g733a5 From c9e5eab6ff54fa4c24ab79894c4415615195db7c Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 19:26:32 +0200 Subject: Update the `thread::Thread` documentation. - Copied the module documentation to `Thread`. - Removed the example because it did not use any method of Thread. --- src/libstd/thread/mod.rs | 36 ++++++++++++------------------------ 1 file changed, 12 insertions(+), 24 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2f7a17af779..d4f6c6c67c5 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -721,33 +721,21 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread. +/// Threads are represented via the `Thread` type, which you can get in one of +/// two ways: /// -/// You can use it to identify a thread (by name, for example). Most of the -/// time, there is no need to directly create a `Thread` struct using the -/// constructor, instead you should use a function like `spawn` to create -/// new threads, see the docs of [`Builder`] and [`spawn`] for more. +/// * By spawning a new thread, e.g. using the [`thread::spawn`][`spawn`] +/// function, and calling [`thread`][`JoinHandle::thread`] on the +/// [`JoinHandle`]. +/// * By requesting the current thread, using the [`thread::current`] function. /// -/// # Examples +/// The [`thread::current`] function is available even for threads not spawned +/// by the APIs of this module. +/// +/// There is usualy no need to create a `Thread` struct yourself, one +/// should instead use a function like `spawn` to create new threads, see the +/// docs of [`Builder`] and [`spawn`] for more details. /// -/// ```no_run -/// # // Note that this example isn't executed by default because it causes -/// # // deadlocks on Windows unfortunately (see #25824) -/// use std::thread::Builder; -/// -/// for i in 0..5 { -/// let thread_name = format!("thread_{}", i); -/// Builder::new() -/// .name(thread_name) // Now you can identify which thread panicked -/// // thanks to the handle's name -/// .spawn(move || { -/// if i == 3 { -/// panic!("I'm scared!!!"); -/// } -/// }) -/// .unwrap(); -/// } -/// ``` /// [`Builder`]: ../../std/thread/struct.Builder.html /// [`spawn`]: ../../std/thread/fn.spawn.html -- cgit 1.4.1-3-g733a5 From 03c9510525c986715af1f1f98c2bc06248c747e8 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 21:43:46 +0200 Subject: Fix typos in `thread::park` documentation. --- src/libstd/thread/mod.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 5373bf273d4..4d931682676 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -518,7 +518,7 @@ pub fn sleep(dur: Duration) { /// # park and unpark /// /// Every thread is equipped with some basic low-level blocking support, via the -/// [`thread::park`][`park`] function and [`thread::Thread::unpark()`][`unpark`] +/// [`thread::park`][`park`] function and [`thread::Thread::unpark`][`unpark`] /// method. [`park`] blocks the current thread, which can then be resumed from /// another thread by calling the [`unpark`] method on the blocked thread's /// handle. @@ -555,6 +555,7 @@ pub fn sleep(dur: Duration) { /// /// ``` /// use std::thread; +/// use std::time::Duration; /// /// let parked_thread = thread::Builder::new() /// .spawn(|| { @@ -598,7 +599,7 @@ pub fn park() { /// Blocks unless or until the current thread's token is made available or /// the specified duration has been reached (may wake spuriously). /// -/// The semantics of this function are equivalent to [`park()`][park] except +/// The semantics of this function are equivalent to [`park`][park] except /// that the thread will be blocked for roughly no longer than `dur`. This /// method should not be used for precise timing due to anomalies such as /// preemption or platform differences that may not cause the maximum @@ -617,7 +618,7 @@ pub fn park_timeout_ms(ms: u32) { /// Blocks unless or until the current thread's token is made available or /// the specified duration has been reached (may wake spuriously). /// -/// The semantics of this function are equivalent to [`park()`][park] except +/// The semantics of this function are equivalent to [`park`][park] except /// that the thread will be blocked for roughly no longer than `dur`. This /// method should not be used for precise timing due to anomalies such as /// preemption or platform differences that may not cause the maximum @@ -780,7 +781,7 @@ impl Thread { /// Atomically makes the handle's token available if it is not already. /// /// Every thread is equipped with some basic low-level blocking support, via - /// the [`park()`][park] function and the `unpark()` method. These can be + /// the [`park`][park] function and the `unpark()` method. These can be /// used as a more CPU-efficient implementation of a spinlock. /// /// See the [park documentation][park] for more details. @@ -789,6 +790,7 @@ impl Thread { /// /// ``` /// use std::thread; + /// use std::time::Duration; /// /// let parked_thread = thread::Builder::new() /// .spawn(|| { -- cgit 1.4.1-3-g733a5 From c655348f26a179193f5d6d1a3a2fbe000a046699 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 13:20:04 +0200 Subject: Add more examples to `thread::spawn` Part of #29378 --- src/libstd/thread/mod.rs | 57 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 6 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4cbcfdbc2d7..c1e894510b9 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -315,6 +315,8 @@ impl Builder { /// thread finishes). The join handle can be used to block on /// termination of the child thread, including recovering its panics. /// + /// For a more complete documentation see [`thread::spawn`][`spawn`]. + /// /// # Errors /// /// Unlike the [`spawn`] free function, this method yields an @@ -392,14 +394,10 @@ impl Builder { /// Panics if the OS fails to create a thread; use [`Builder::spawn`] /// to recover from such errors. /// -/// [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html -/// [`join`]: ../../std/thread/struct.JoinHandle.html#method.join -/// [`Err`]: ../../std/result/enum.Result.html#variant.Err -/// [`panic`]: ../../std/macro.panic.html -/// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn -/// /// # Examples /// +/// Simple thread creation. +/// /// ``` /// use std::thread; /// @@ -409,6 +407,53 @@ impl Builder { /// /// handler.join().unwrap(); /// ``` +/// +/// As mentionned in the module documentation, threads are usualy made to +/// communicate using [`channel`s][`channels`], here is how it usually looks. +/// +/// This example also shows how to use `move`, in order to give ownership +/// of values to a thread. +/// +/// ``` +/// use std::thread; +/// use std::sync::mpsc::channel; +/// +/// let (tx, rx) = channel(); +/// +/// let sender = thread::spawn(move || { +/// tx.send("Hello, thread".to_owned()); +/// }); +/// +/// let receiver = thread::spawn(move || { +/// println!("{}", rx.recv().unwrap()); +/// }); +/// +/// sender.join(); +/// receiver.join(); +/// ``` +/// +/// A thread can also return a value through its [`JoinHandle`], you can use +/// this to make asynchronous computations (futures might be more appropriate +/// though). +/// +/// ``` +/// use std::thread; +/// +/// let computation = thread::spawn(|| { +/// // Some expensive computation. +/// 42 +/// }); +/// +/// let result = computation.join().unwrap(); +/// println!("{}", v); +/// ``` +/// +/// [`channels`]: ../../std/sync/mpsc/index.html +/// [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html +/// [`join`]: ../../std/thread/struct.JoinHandle.html#method.join +/// [`Err`]: ../../std/result/enum.Result.html#variant.Err +/// [`panic`]: ../../std/macro.panic.html +/// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn #[stable(feature = "rust1", since = "1.0.0")] pub fn spawn(f: F) -> JoinHandle where F: FnOnce() -> T, F: Send + 'static, T: Send + 'static -- cgit 1.4.1-3-g733a5 From 9db31206f597444258a46220f39fde13a76453e2 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 13:27:22 +0200 Subject: Add a link to `thread::Builder` in `thread::spawn` --- src/libstd/thread/mod.rs | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index c1e894510b9..19adf3e3c3f 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -389,6 +389,10 @@ impl Builder { /// panics, [`join`] will return an [`Err`] containing the argument given to /// [`panic`]. /// +/// This will create a thread using default parameters of [`Builder`], if you +/// want to specify the stack size or the name of the thread, use this API +/// instead. +/// /// # Panics /// /// Panics if the OS fails to create a thread; use [`Builder::spawn`] @@ -454,6 +458,7 @@ impl Builder { /// [`Err`]: ../../std/result/enum.Result.html#variant.Err /// [`panic`]: ../../std/macro.panic.html /// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn +/// [`Builder`]: ../../std/thread/struct.Builder.html #[stable(feature = "rust1", since = "1.0.0")] pub fn spawn(f: F) -> JoinHandle where F: FnOnce() -> T, F: Send + 'static, T: Send + 'static -- cgit 1.4.1-3-g733a5 From 323a774c2f64619623c45aec068cf6c1c905d314 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 16:52:26 +0200 Subject: Address review comments --- src/libstd/thread/mod.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index d4f6c6c67c5..9fc1def99b1 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -244,7 +244,7 @@ impl Builder { /// Generates the base configuration for spawning a thread, from which /// configuration methods can be chained. /// - /// If the [`stack_size`][stack_size] field is not specified, the stack size + /// If the [`stack_size`] field is not specified, the stack size /// will be the `RUST_MIN_STACK` environment variable, if it is /// not specified either, a sensible default size will be set (2MB as /// of the writting of this doc). @@ -265,7 +265,7 @@ impl Builder { /// handler.join().unwrap(); /// ``` /// - /// [stack_size]: ../../std/thread/struct.Builder.html#method.stack_size + /// [`stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size #[stable(feature = "rust1", since = "1.0.0")] pub fn new() -> Builder { Builder { @@ -721,6 +721,8 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] +/// A handle to a thread. +/// /// Threads are represented via the `Thread` type, which you can get in one of /// two ways: /// -- cgit 1.4.1-3-g733a5 From 656efcd3ab029491fd0bd01f3b596516884cabe1 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 16:57:03 +0200 Subject: Address review comments --- src/libstd/thread/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 19adf3e3c3f..dd8892d6660 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -400,7 +400,7 @@ impl Builder { /// /// # Examples /// -/// Simple thread creation. +/// Creating a thread. /// /// ``` /// use std::thread; @@ -413,7 +413,7 @@ impl Builder { /// ``` /// /// As mentionned in the module documentation, threads are usualy made to -/// communicate using [`channel`s][`channels`], here is how it usually looks. +/// communicate using [`channels`], here is how it usually looks. /// /// This example also shows how to use `move`, in order to give ownership /// of values to a thread. -- cgit 1.4.1-3-g733a5 From afe74c3900aa00373a0d5edd2bd433870822c40a Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 19:02:43 +0200 Subject: Fix link --- src/libstd/thread/mod.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4d931682676..9a7239d297c 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -594,21 +594,21 @@ pub fn park() { *guard = false; } -/// Use [park_timeout]. +/// Use [`park_timeout`]. /// /// Blocks unless or until the current thread's token is made available or /// the specified duration has been reached (may wake spuriously). /// -/// The semantics of this function are equivalent to [`park`][park] except +/// The semantics of this function are equivalent to [`park`] except /// that the thread will be blocked for roughly no longer than `dur`. This /// method should not be used for precise timing due to anomalies such as /// preemption or platform differences that may not cause the maximum /// amount of time waited to be precisely `ms` long. /// -/// See the [park documentation][park] for more detail. +/// See the [park documentation][`park`] for more detail. /// -/// [park_timeout]: fn.park_timeout.html -/// [park]: ../../std/thread/fn.park.html +/// [`park_timeout`]: fn.park_timeout.html +/// [`park`]: ../../std/thread/fn.park.html #[stable(feature = "rust1", since = "1.0.0")] #[rustc_deprecated(since = "1.6.0", reason = "replaced by `std::thread::park_timeout`")] pub fn park_timeout_ms(ms: u32) { -- cgit 1.4.1-3-g733a5 From 202086e48ff3ca955a52137d71ca8713f39cd5ff Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Tue, 9 May 2017 19:06:56 +0200 Subject: Fix warnings in examples --- src/libstd/thread/mod.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index dd8892d6660..425cb0ada08 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -425,15 +425,15 @@ impl Builder { /// let (tx, rx) = channel(); /// /// let sender = thread::spawn(move || { -/// tx.send("Hello, thread".to_owned()); +/// let _ = tx.send("Hello, thread".to_owned()); /// }); /// /// let receiver = thread::spawn(move || { /// println!("{}", rx.recv().unwrap()); /// }); /// -/// sender.join(); -/// receiver.join(); +/// let _ = sender.join(); +/// let _ = receiver.join(); /// ``` /// /// A thread can also return a value through its [`JoinHandle`], you can use @@ -449,7 +449,7 @@ impl Builder { /// }); /// /// let result = computation.join().unwrap(); -/// println!("{}", v); +/// println!("{}", result); /// ``` /// /// [`channels`]: ../../std/sync/mpsc/index.html -- cgit 1.4.1-3-g733a5 From ca8b75466cef854d30fdf7614c2358b1eb46816e Mon Sep 17 00:00:00 2001 From: Yamakaky Date: Sat, 4 Mar 2017 10:27:52 -0500 Subject: Don't show the std frames before user code on unwinding. When `RUST_BACKTRACE=1`, remove all frames after `__rust_maybe_catch_panic`. Tested on `main`, threads, tests and benches. Cleaning of the top of the stacktrace is let to a future PR. Fixes #40201 See #41815 --- src/libstd/rt.rs | 7 +++--- src/libstd/sys_common/backtrace.rs | 44 ++++++++++++++++++++++++++++++++++---- src/libstd/thread/mod.rs | 4 +++- src/libtest/lib.rs | 26 +++++++++++++++++----- 4 files changed, 68 insertions(+), 13 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/rt.rs b/src/libstd/rt.rs index 6c791cd336d..acff7faf8a7 100644 --- a/src/libstd/rt.rs +++ b/src/libstd/rt.rs @@ -29,8 +29,7 @@ pub use panicking::{begin_panic, begin_panic_fmt, update_panic_count}; #[cfg(not(test))] #[lang = "start"] -fn lang_start(main: *const u8, argc: isize, argv: *const *const u8) -> isize { - use mem; +fn lang_start(main: fn(), argc: isize, argv: *const *const u8) -> isize { use panic; use sys; use sys_common; @@ -54,7 +53,9 @@ fn lang_start(main: *const u8, argc: isize, argv: *const *const u8) -> isize { sys::args::init(argc, argv); // Let's run some code! - let res = panic::catch_unwind(mem::transmute::<_, fn()>(main)); + let res = panic::catch_unwind(|| { + ::sys_common::backtrace::__rust_begin_short_backtrace(main) + }); sys_common::cleanup(); res.is_err() }; diff --git a/src/libstd/sys_common/backtrace.rs b/src/libstd/sys_common/backtrace.rs index 04fe5f78b03..617218fe7a5 100644 --- a/src/libstd/sys_common/backtrace.rs +++ b/src/libstd/sys_common/backtrace.rs @@ -93,11 +93,47 @@ fn _print(w: &mut Write, format: PrintFormat) -> io::Result<()> { Ok(()) } -fn filter_frames(_frames: &[Frame], - _format: PrintFormat, - _context: &BacktraceContext) -> (usize, usize) +/// Returns a number of frames to remove at the beginning and at the end of the +/// backtrace, according to the backtrace format. +fn filter_frames(frames: &[Frame], + format: PrintFormat, + context: &BacktraceContext) -> (usize, usize) { - (0, 0) + if format == PrintFormat::Full { + return (0, 0); + } + + let skipped_before = 0; + + let skipped_after = frames.len() - frames.iter().position(|frame| { + let mut is_marker = false; + let _ = resolve_symname(*frame, |symname| { + if let Some(mangled_symbol_name) = symname { + // Use grep to find the concerned functions + if mangled_symbol_name.contains("__rust_begin_short_backtrace") { + is_marker = true; + } + } + Ok(()) + }, context); + is_marker + }).unwrap_or(frames.len()); + + if skipped_before + skipped_after >= frames.len() { + // Avoid showing completely empty backtraces + return (0, 0); + } + + (skipped_before, skipped_after) +} + + +/// Fixed frame used to clean the backtrace with `RUST_BACKTRACE=1`. +#[inline(never)] +pub fn __rust_begin_short_backtrace(f: F) -> T + where F: FnOnce() -> T, F: Send + 'static, T: Send + 'static +{ + f() } /// Controls how the backtrace should be formated. diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 04cd28df445..3101d08244e 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -358,7 +358,9 @@ impl Builder { } unsafe { thread_info::set(imp::guard::current(), their_thread); - let try_result = panic::catch_unwind(panic::AssertUnwindSafe(f)); + let try_result = panic::catch_unwind(panic::AssertUnwindSafe(|| { + ::sys_common::backtrace::__rust_begin_short_backtrace(f) + })); *their_packet.get() = Some(try_result); } }; diff --git a/src/libtest/lib.rs b/src/libtest/lib.rs index 35f2fbca69f..0d615db3deb 100644 --- a/src/libtest/lib.rs +++ b/src/libtest/lib.rs @@ -1314,12 +1314,16 @@ pub fn convert_benchmarks_to_tests(tests: Vec) -> Vec { DynTestFn(Box::new(move |()| { - bench::run_once(|b| bench.run(b)) + bench::run_once(|b| { + __rust_begin_short_backtrace(|| bench.run(b)) + }) })) } StaticBenchFn(benchfn) => { DynTestFn(Box::new(move |()| { - bench::run_once(|b| benchfn(b)) + bench::run_once(|b| { + __rust_begin_short_backtrace(|| benchfn(b)) + }) })) } f => f, @@ -1425,12 +1429,24 @@ pub fn run_test(opts: &TestOpts, monitor_ch.send((desc, TrMetrics(mm), Vec::new())).unwrap(); return; } - DynTestFn(f) => run_test_inner(desc, monitor_ch, opts.nocapture, f), - StaticTestFn(f) => run_test_inner(desc, monitor_ch, opts.nocapture, - Box::new(move |()| f())), + DynTestFn(f) => { + let cb = move |()| { + __rust_begin_short_backtrace(|| f.call_box(())) + }; + run_test_inner(desc, monitor_ch, opts.nocapture, Box::new(cb)) + } + StaticTestFn(f) => + run_test_inner(desc, monitor_ch, opts.nocapture, + Box::new(move |()| __rust_begin_short_backtrace(f))), } } +/// Fixed frame used to clean the backtrace with `RUST_BACKTRACE=1`. +#[inline(never)] +fn __rust_begin_short_backtrace(f: F) { + f() +} + fn calc_result(desc: &TestDesc, task_result: Result<(), Box>) -> TestResult { match (&desc.should_panic, task_result) { (&ShouldPanic::No, Ok(())) | -- cgit 1.4.1-3-g733a5 From fe7b6db39b6efa064ab795103342ca3d298dc943 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Wed, 10 May 2017 10:44:58 +0200 Subject: Fix typos in doc --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 425cb0ada08..e81300d6dc8 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -412,7 +412,7 @@ impl Builder { /// handler.join().unwrap(); /// ``` /// -/// As mentionned in the module documentation, threads are usualy made to +/// As mentioned in the module documentation, threads are usually made to /// communicate using [`channels`], here is how it usually looks. /// /// This example also shows how to use `move`, in order to give ownership -- cgit 1.4.1-3-g733a5 From e42875ce6dfc0102b00e6725f403c2f5a1b59fce Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 11 May 2017 06:27:01 +0200 Subject: doc: break into 2 sentences --- src/libstd/thread/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4432f898e04..4ddd92f1592 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -245,8 +245,8 @@ impl Builder { /// configuration methods can be chained. /// /// If the [`stack_size`] field is not specified, the stack size - /// will be the `RUST_MIN_STACK` environment variable, if it is - /// not specified either, a sensible default size will be set (2MB as + /// will be the `RUST_MIN_STACK` environment variable. If it is + /// not specified either, a sensible default will be set (2MB as /// of the writting of this doc). /// /// # Examples -- cgit 1.4.1-3-g733a5 From a9cb094879fabd23774a0d9dcfed7f3eeb9a4aff Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sat, 13 May 2017 21:42:51 +0200 Subject: Explain why `thread::yield_now` could be used. Part of #29378. --- src/libstd/thread/mod.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 200368be275..8f1a88ed305 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -468,6 +468,23 @@ pub fn current() -> Thread { /// Cooperatively gives up a timeslice to the OS scheduler. /// +/// This is used when the programmer knows that the thread will have nothing +/// to do for some time, and thus avoid wasting computing time. +/// +/// For example when polling on a resource, it is common to check that it is +/// available, and if not to yield in order to avoid busy waiting. +/// +/// Thus the pattern of `yield`ing after a failed poll is rather common when +/// implementing low-level shared resources or synchronization primitives. +/// +/// However programmers will usualy prefer to use, [`channel`]s, [`Condvar`]s, +/// [`Mutex`]es or [`join`] for their synchronisation routines, as they avoid +/// thinking about thread schedulling. +/// +/// Note that [`channel`]s for example are implemented using this primitive. +/// Indeed when you call `send` or `recv`, which are blocking, they will yield +/// if the channel is not available. +/// /// # Examples /// /// ``` @@ -475,6 +492,12 @@ pub fn current() -> Thread { /// /// thread::yield_now(); /// ``` +/// +/// [`channel`]: ../../std/sync/mpsc/index.html +/// [`spawn`]: ../../std/thread/fn.spawn.html +/// [`join`]: ../../std/thread/struct.JoinHandle.html#method.join +/// [`Mutex`]: ../../std/sync/struct.Mutex.html +/// [`Condvar`]: ../../std/sync/struct.Condvar.html #[stable(feature = "rust1", since = "1.0.0")] pub fn yield_now() { imp::Thread::yield_now() -- cgit 1.4.1-3-g733a5 From 770bd57ea5bb369067103841004dfe595ab22490 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sat, 13 May 2017 20:34:40 +0200 Subject: Add `'static` and `Send` constraints explanations to `thread::spawn` Part of #29378. --- src/libstd/thread/mod.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 200368be275..d807424129e 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -367,6 +367,26 @@ impl Builder { /// want to specify the stack size or the name of the thread, use this API /// instead. /// +/// As you can see in the signature of `spawn` there are two constraints on +/// both the closure given to `spawn` and its return value, let's explain them: +/// +/// - The `'static` constraint means that the closure and its return value +/// must have a lifetime of the whole program execution. The reason for this +/// is that threads can `detach` and outlive the lifetime they have been +/// created in. +/// Indeed if the thread, and by extension its return value, can outlive their +/// caller, we need to make sure that they will be valid afterwards, and since +/// we *can't* know when it will return we need to have them valid as long as +/// possible, that is until the end of the program, hence the `'static` +/// lifetime. +/// - The [`Send`] constraint is because the closure will need to be passed +/// *by value* from the thread where it is spawned to the new thread. Its +/// return value will need to be passed from the new thread to the thread +/// where it is `join`ed. +/// As a reminder, the [`Send`] marker trait, expresses that it is safe to be +/// passed from thread to thread. [`Sync`] expresses that it is safe to have a +/// reference be passed from thread to thread. +/// /// # Panics /// /// Panics if the OS fails to create a thread; use [`Builder::spawn`] @@ -433,6 +453,8 @@ impl Builder { /// [`panic`]: ../../std/macro.panic.html /// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn /// [`Builder`]: ../../std/thread/struct.Builder.html +/// [`Send`]: ../../std/marker/trait.Send.html +/// [`Sync`]: ../../std/marker/trait.Sync.html #[stable(feature = "rust1", since = "1.0.0")] pub fn spawn(f: F) -> JoinHandle where F: FnOnce() -> T, F: Send + 'static, T: Send + 'static -- cgit 1.4.1-3-g733a5 From a51777ec874e31b29d85efaa186fe4841257b168 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 14 May 2017 19:35:36 +0200 Subject: Improve `thread::Builder` documentation. Part of #29378 . - In particular explains *why* we would use the builder instead of the free function. - Changes the parent-child explanation for a spawned-caller. - Add link to `io::Result` in `thread::Builder` - Corrects the `thread::Builder::spawn` documentation. --- src/libstd/thread/mod.rs | 49 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 11 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 200368be275..1f079c21f57 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -180,8 +180,33 @@ pub use self::local::{LocalKey, LocalKeyState}; // Builder //////////////////////////////////////////////////////////////////////////////// -/// Thread configuration. Provides detailed control over the properties -/// and behavior of new threads. +/// Thread factory, which can be used in order to configure the properties of +/// a new thread. +/// +/// Methods can be chained on it in order to configure it. +/// +/// The two configurations available are: +/// +/// - [`name`]: allows to give a name to the thread which is currently +/// only used in `panic` messages. +/// - [`stack_size`]: specifies the desired stack size. Note that this can +/// be overriden by the OS. +/// +/// If the [`stack_size`] field is not specified, the stack size +/// will be the `RUST_MIN_STACK` environment variable. If it is +/// not specified either, a sensible default will be set. +/// +/// If the [`name`] field is not specified, the thread will not be named. +/// +/// The [`spawn`] method will take ownership of the builder and create an +/// [`io::Result`] to the thread handle with the given configuration. +/// +/// The [`thread::spawn`] free function uses a `Builder` with default +/// configuration and [`unwrap`]s its return value. +/// +/// You may want to use [`spawn`] instead of [`thread::spawn`], when you want +/// to recover from a failure to launch a thread, indeed the free function will +/// panick where the `Builder` method will return a [`io::Result`]. /// /// # Examples /// @@ -196,6 +221,13 @@ pub use self::local::{LocalKey, LocalKeyState}; /// /// handler.join().unwrap(); /// ``` +/// +/// [`thread::spawn`]: ../../std/thread/fn.spawn.html +/// [`stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size +/// [`name`]: ../../std/thread/struct.Builder.html#method.name +/// [`spawn`]: ../../std/thread/struct.Builder.html#method.spawn +/// [`io::Result`]: ../../std/io/type.Result.html +/// [`unwrap`]: ../../std/result/enum.Result.html#method.unwrap #[stable(feature = "rust1", since = "1.0.0")] #[derive(Debug)] pub struct Builder { @@ -209,11 +241,6 @@ impl Builder { /// Generates the base configuration for spawning a thread, from which /// configuration methods can be chained. /// - /// If the [`stack_size`] field is not specified, the stack size - /// will be the `RUST_MIN_STACK` environment variable. If it is - /// not specified either, a sensible default will be set (2MB as - /// of the writting of this doc). - /// /// # Examples /// /// ``` @@ -229,8 +256,6 @@ impl Builder { /// /// handler.join().unwrap(); /// ``` - /// - /// [`stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size #[stable(feature = "rust1", since = "1.0.0")] pub fn new() -> Builder { Builder { @@ -280,9 +305,10 @@ impl Builder { self } - /// Spawns a new thread, and returns a join handle for it. + /// Spawns a new thread by taking ownership of the `Builder`, and returns an + /// [`io::Result`] to its [`JoinHandle`]. /// - /// The child thread may outlive the parent (unless the parent thread + /// The spawned thread may outlive the caller (unless the caller thread /// is the main thread; the whole process is terminated when the main /// thread finishes). The join handle can be used to block on /// termination of the child thread, including recovering its panics. @@ -297,6 +323,7 @@ impl Builder { /// /// [`spawn`]: ../../std/thread/fn.spawn.html /// [`io::Result`]: ../../std/io/type.Result.html + /// [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html /// /// # Examples /// -- cgit 1.4.1-3-g733a5 From f92bd3dbd005bb0bbcdeb64eea263634428d660a Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 14 May 2017 20:06:54 +0200 Subject: Add links to the `thread::LocalKey` doc. Part of #29378 . --- src/libstd/thread/local.rs | 45 ++++++++++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 15 deletions(-) (limited to 'src/libstd/thread') diff --git a/src/libstd/thread/local.rs b/src/libstd/thread/local.rs index e2b22b1d89f..c2c6e6cf87d 100644 --- a/src/libstd/thread/local.rs +++ b/src/libstd/thread/local.rs @@ -19,16 +19,16 @@ use mem; /// A thread local storage key which owns its contents. /// /// This key uses the fastest possible implementation available to it for the -/// target platform. It is instantiated with the `thread_local!` macro and the -/// primary method is the `with` method. +/// target platform. It is instantiated with the [`thread_local!`] macro and the +/// primary method is the [`with`] method. /// -/// The `with` method yields a reference to the contained value which cannot be +/// The [`with`] method yields a reference to the contained value which cannot be /// sent across threads or escape the given closure. /// /// # Initialization and Destruction /// -/// Initialization is dynamically performed on the first call to `with()` -/// within a thread, and values that implement `Drop` get destructed when a +/// Initialization is dynamically performed on the first call to [`with`] +/// within a thread, and values that implement [`Drop`] get destructed when a /// thread exits. Some caveats apply, which are explained below. /// /// # Examples @@ -77,6 +77,10 @@ use mem; /// 3. On macOS, initializing TLS during destruction of other TLS slots can /// sometimes cancel *all* destructors for the current thread, whether or not /// the slots have already had their destructors run or not. +/// +/// [`with`]: ../../std/thread/struct.LocalKey.html#method.with +/// [`thread_local!`]: ../../std/macro.thread_local.html +/// [`Drop`]: ../../std/ops/trait.Drop.html #[stable(feature = "rust1", since = "1.0.0")] pub struct LocalKey { // This outer `LocalKey` type is what's going to be stored in statics, @@ -106,7 +110,7 @@ impl fmt::Debug for LocalKey { } } -/// Declare a new thread local storage key of type `std::thread::LocalKey`. +/// Declare a new thread local storage key of type [`std::thread::LocalKey`]. /// /// # Syntax /// @@ -124,8 +128,10 @@ impl fmt::Debug for LocalKey { /// # fn main() {} /// ``` /// -/// See [LocalKey documentation](thread/struct.LocalKey.html) for more +/// See [LocalKey documentation][`std::thread::LocalKey`] for more /// information. +/// +/// [`std::thread::LocalKey`]: ../std/thread/struct.LocalKey.html #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] #[allow_internal_unstable] @@ -195,11 +201,13 @@ macro_rules! __thread_local_inner { #[derive(Debug, Eq, PartialEq, Copy, Clone)] pub enum LocalKeyState { /// All keys are in this state whenever a thread starts. Keys will - /// transition to the `Valid` state once the first call to `with` happens + /// transition to the `Valid` state once the first call to [`with`] happens /// and the initialization expression succeeds. /// /// Keys in the `Uninitialized` state will yield a reference to the closure - /// passed to `with` so long as the initialization routine does not panic. + /// passed to [`with`] so long as the initialization routine does not panic. + /// + /// [`with`]: ../../std/thread/struct.LocalKey.html#method.with Uninitialized, /// Once a key has been accessed successfully, it will enter the `Valid` @@ -208,7 +216,9 @@ pub enum LocalKeyState { /// `Destroyed` state. /// /// Keys in the `Valid` state will be guaranteed to yield a reference to the - /// closure passed to `with`. + /// closure passed to [`with`]. + /// + /// [`with`]: ../../std/thread/struct.LocalKey.html#method.with Valid, /// When a thread exits, the destructors for keys will be run (if @@ -216,7 +226,9 @@ pub enum LocalKeyState { /// destructor has run, a key is in the `Destroyed` state. /// /// Keys in the `Destroyed` states will trigger a panic when accessed via - /// `with`. + /// [`with`]. + /// + /// [`with`]: ../../std/thread/struct.LocalKey.html#method.with Destroyed, } @@ -283,23 +295,26 @@ impl LocalKey { /// Query the current state of this key. /// /// A key is initially in the `Uninitialized` state whenever a thread - /// starts. It will remain in this state up until the first call to `with` + /// starts. It will remain in this state up until the first call to [`with`] /// within a thread has run the initialization expression successfully. /// /// Once the initialization expression succeeds, the key transitions to the - /// `Valid` state which will guarantee that future calls to `with` will + /// `Valid` state which will guarantee that future calls to [`with`] will /// succeed within the thread. /// /// When a thread exits, each key will be destroyed in turn, and as keys are /// destroyed they will enter the `Destroyed` state just before the /// destructor starts to run. Keys may remain in the `Destroyed` state after /// destruction has completed. Keys without destructors (e.g. with types - /// that are `Copy`), may never enter the `Destroyed` state. + /// that are [`Copy`]), may never enter the `Destroyed` state. /// /// Keys in the `Uninitialized` state can be accessed so long as the /// initialization does not panic. Keys in the `Valid` state are guaranteed /// to be able to be accessed. Keys in the `Destroyed` state will panic on - /// any call to `with`. + /// any call to [`with`]. + /// + /// [`with`]: ../../std/thread/struct.LocalKey.html#method.with + /// [`Copy`]: ../../std/marker/trait.Copy.html #[unstable(feature = "thread_local_state", reason = "state querying was recently added", issue = "27716")] -- cgit 1.4.1-3-g733a5 From 66237afce454db9235525dc715238568c492f54b Mon Sep 17 00:00:00 2001 From: Ian Douglas Scott Date: Sun, 21 May 2017 12:38:07 -0700 Subject: Fix building without backtrace feature, which was broken in ca8b754 Fixes #42139 --- src/libstd/rt.rs | 5 +++++ src/libstd/thread/mod.rs | 3 +++ 2 files changed, 8 insertions(+) (limited to 'src/libstd/thread') diff --git a/src/libstd/rt.rs b/src/libstd/rt.rs index acff7faf8a7..06fd838ea06 100644 --- a/src/libstd/rt.rs +++ b/src/libstd/rt.rs @@ -35,6 +35,8 @@ fn lang_start(main: fn(), argc: isize, argv: *const *const u8) -> isize { use sys_common; use sys_common::thread_info; use thread::Thread; + #[cfg(not(feature = "backtrace"))] + use mem; sys::init(); @@ -53,9 +55,12 @@ fn lang_start(main: fn(), argc: isize, argv: *const *const u8) -> isize { sys::args::init(argc, argv); // Let's run some code! + #[cfg(feature = "backtrace")] let res = panic::catch_unwind(|| { ::sys_common::backtrace::__rust_begin_short_backtrace(main) }); + #[cfg(not(feature = "backtrace"))] + let res = panic::catch_unwind(mem::transmute::<_, fn()>(main)); sys_common::cleanup(); res.is_err() }; diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 154406a1d8b..75717abb4ad 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -359,9 +359,12 @@ impl Builder { } unsafe { thread_info::set(imp::guard::current(), their_thread); + #[cfg(feature = "backtrace")] let try_result = panic::catch_unwind(panic::AssertUnwindSafe(|| { ::sys_common::backtrace::__rust_begin_short_backtrace(f) })); + #[cfg(not(feature = "backtrace"))] + let try_result = panic::catch_unwind(panic::AssertUnwindSafe(f)); *their_packet.get() = Some(try_result); } }; -- cgit 1.4.1-3-g733a5