From f2ff9857cd74132486538cc92c491fa2c331c9b4 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 7 Nov 2016 12:21:06 +0100 Subject: [PATCH] Add missing urls and few local rewrites --- src/libcore/iter/iterator.rs | 146 ++++++++++++++++++++++------------- 1 file changed, 92 insertions(+), 54 deletions(-) diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 5a12f5db19d..f6b74a91c19 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -35,11 +35,14 @@ pub trait Iterator { /// Advances the iterator and returns the next value. /// - /// Returns `None` when iteration is finished. Individual iterator + /// Returns [`None`] when iteration is finished. Individual iterator /// implementations may choose to resume iteration, and so calling `next()` - /// again may or may not eventually start returning `Some(Item)` again at some + /// again may or may not eventually start returning [`Some(Item)`] again at some /// point. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// [`Some(Item)`]: ../../std/option/enum.Option.html#variant.Some + /// /// # Examples /// /// Basic usage: @@ -69,9 +72,9 @@ pub trait Iterator { /// Specifically, `size_hint()` returns a tuple where the first element /// is the lower bound, and the second element is the upper bound. /// - /// The second half of the tuple that is returned is an `Option`. A - /// `None` here means that either there is no known upper bound, or the - /// upper bound is larger than `usize`. + /// The second half of the tuple that is returned is an [`Option`]`<`[`usize`]`>`. + /// A [`None`] here means that either there is no known upper bound, or the + /// upper bound is larger than [`usize`]. /// /// # Implementation notes /// @@ -91,6 +94,10 @@ pub trait Iterator { /// The default implementation returns `(0, None)` which is correct for any /// iterator. /// + /// [`usize`]: ../../std/primitive.usize.html + /// [`Option`]: ../../std/option/enum.Option.html + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -134,23 +141,26 @@ fn size_hint(&self) -> (usize, Option) { (0, None) } /// Consumes the iterator, counting the number of iterations and returning it. /// /// This method will evaluate the iterator until its [`next()`] returns - /// `None`. Once `None` is encountered, `count()` returns the number of + /// [`None`]. Once [`None`] is encountered, `count()` returns the number of /// times it called [`next()`]. /// /// [`next()`]: #tymethod.next + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Overflow Behavior /// /// The method does no guarding against overflows, so counting elements of - /// an iterator with more than `usize::MAX` elements either produces the + /// an iterator with more than [`usize::MAX`] elements either produces the /// wrong result or panics. If debug assertions are enabled, a panic is /// guaranteed. /// /// # Panics /// - /// This function might panic if the iterator has more than `usize::MAX` + /// This function might panic if the iterator has more than [`usize::MAX`] /// elements. /// + /// [`usize::MAX`]: ../../std/isize/constant.MAX.html + /// /// # Examples /// /// Basic usage: @@ -172,10 +182,12 @@ fn count(self) -> usize where Self: Sized { /// Consumes the iterator, returning the last element. /// - /// This method will evaluate the iterator until it returns `None`. While - /// doing so, it keeps track of the current element. After `None` is + /// This method will evaluate the iterator until it returns [`None`]. While + /// doing so, it keeps track of the current element. After [`None`] is /// returned, `last()` will then return the last element it saw. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -202,9 +214,11 @@ fn last(self) -> Option where Self: Sized { /// Like most indexing operations, the count starts from zero, so `nth(0)` /// returns the first value, `nth(1)` the second, and so on. /// - /// `nth()` will return `None` if `n` is greater than or equal to the length of the + /// `nth()` will return [`None`] if `n` is greater than or equal to the length of the /// iterator. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -306,8 +320,8 @@ fn chain(self, other: U) -> Chain where /// /// In other words, it zips two iterators together, into a single one. /// - /// When either iterator returns `None`, all further calls to `next()` - /// will return `None`. + /// When either iterator returns [`None`], all further calls to [`next()`] + /// will return [`None`]. /// /// # Examples /// @@ -346,7 +360,7 @@ fn chain(self, other: U) -> Chain where /// ``` /// /// `zip()` is often used to zip an infinite iterator to a finite one. - /// This works because the finite iterator will eventually return `None`, + /// This works because the finite iterator will eventually return [`None`], /// ending the zipper. Zipping with `(0..)` can look a lot like [`enumerate()`]: /// /// ``` @@ -365,6 +379,8 @@ fn chain(self, other: U) -> Chain where /// ``` /// /// [`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")] fn zip(self, other: U) -> Zip where @@ -501,11 +517,9 @@ fn filter

(self, predicate: P) -> Filter where /// /// The closure must return an [`Option`]. `filter_map()` creates an /// iterator which calls this closure on each element. If the closure - /// returns `Some(element)`, then that element is returned. If the - /// closure returns `None`, it will try again, and call the closure on the - /// next element, seeing if it will return `Some`. - /// - /// [`Option`]: ../../std/option/enum.Option.html + /// returns [`Some(element)`][`Some`], then that element is returned. If the + /// 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 /// part: @@ -513,11 +527,11 @@ fn filter

(self, predicate: P) -> Filter where /// [`filter()`]: #method.filter /// [`map()`]: #method.map /// - /// > If the closure returns `Some(element)`, then that element is returned. + /// > If the closure returns [`Some(element)`][`Some`], then that element is returned. /// /// In other words, it removes the [`Option`] layer automatically. If your /// mapping is already returning an [`Option`] and you want to skip over - /// `None`s, then `filter_map()` is much, much nicer to use. + /// [`None`]s, then `filter_map()` is much, much nicer to use. /// /// # Examples /// @@ -547,7 +561,11 @@ fn filter

(self, predicate: P) -> Filter where /// assert_eq!(iter.next(), None); /// ``` /// - /// There's an extra layer of `Some` in there. + /// There's an extra layer of [`Some`] in there. + /// + /// [`Option`]: ../../std/option/enum.Option.html + /// [`Some`]: ../../std/option/enum.Option.html#variant.Some + /// [`None`]: ../../std/option/enum.Option.html#variant.None #[inline] #[stable(feature = "rust1", since = "1.0.0")] fn filter_map(self, f: F) -> FilterMap where @@ -567,21 +585,20 @@ fn filter_map(self, f: F) -> FilterMap where /// different sized integer, the [`zip()`] function provides similar /// functionality. /// - /// [`usize`]: ../../std/primitive.usize.html - /// [`zip()`]: #method.zip - /// /// # Overflow Behavior /// /// The method does no guarding against overflows, so enumerating more than /// [`usize::MAX`] elements either produces the wrong result or panics. If /// debug assertions are enabled, a panic is guaranteed. /// - /// [`usize::MAX`]: ../../std/usize/constant.MAX.html - /// /// # Panics /// /// The returned iterator might panic if the to-be-returned index would - /// overflow a `usize`. + /// overflow a [`usize`]. + /// + /// [`usize::MAX`]: ../../std/usize/constant.MAX.html + /// [`usize`]: ../../std/primitive.usize.html + /// [`zip()`]: #method.zip /// /// # Examples /// @@ -607,12 +624,13 @@ fn enumerate(self) -> Enumerate where Self: Sized { /// 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 /// /// # Examples /// @@ -894,12 +912,12 @@ fn scan(self, initial_state: St, f: F) -> Scan /// an extra layer of indirection. `flat_map()` will remove this extra layer /// on its own. /// - /// [`map()`]: #method.map - /// /// 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 + /// /// # Examples /// /// Basic usage: @@ -921,11 +939,14 @@ fn flat_map(self, f: F) -> FlatMap FlatMap{iter: self, f: f, frontiter: None, backiter: None } } - /// Creates an iterator which ends after the first `None`. + /// Creates an iterator which ends after the first [`None`]. /// - /// After an iterator returns `None`, future calls may or may not yield - /// `Some(T)` again. `fuse()` adapts an iterator, ensuring that after a - /// `None` is given, it will always return `None` forever. + /// After an iterator returns [`None`], future calls may or may not yield + /// [`Some(T)`] again. `fuse()` adapts an iterator, ensuring that after a + /// [`None`] is given, it will always return [`None`] forever. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// [`Some(T)`]: ../../std/option/enum.Option.html#variant.Some /// /// # Examples /// @@ -1082,19 +1103,15 @@ fn by_ref(&mut self) -> &mut Self where Self: Sized { self } /// 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 /// not think of as 'collections' actually are. For example, a [`String`] /// is a collection of [`char`]s. And a collection of [`Result`] can - /// be thought of as single `Result, E>`. See the examples + /// be thought of as single [`Result`]`, E>`. See the examples /// below for more. /// - /// [`String`]: ../../std/string/struct.String.html - /// [`Result`]: ../../std/result/enum.Result.html - /// [`char`]: ../../std/primitive.char.html - /// /// Because `collect()` is so general, it can cause problems with type /// inference. As such, `collect()` is one of the few times you'll see /// the syntax affectionately known as the 'turbofish': `::<>`. This @@ -1172,7 +1189,7 @@ fn by_ref(&mut self) -> &mut Self where Self: Sized { self } /// assert_eq!("hello", hello); /// ``` /// - /// If you have a list of [`Result`]s, you can use `collect()` to + /// If you have a list of [`Result`][`Result`]s, you can use `collect()` to /// see if any of them failed: /// /// ``` @@ -1190,6 +1207,11 @@ fn by_ref(&mut self) -> &mut Self where Self: Sized { self } /// // gives us the list of answers /// assert_eq!(Ok(vec![1, 3]), result); /// ``` + /// + /// [`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 #[inline] #[stable(feature = "rust1", since = "1.0.0")] fn collect>(self) -> B where Self: Sized { @@ -1281,6 +1303,8 @@ fn partition(self, mut f: F) -> (B, B) where /// use a `for` loop with a list of things to build up a result. Those /// can be turned into `fold()`s: /// + /// [`for`]: ../../book/loops.html#for + /// /// ``` /// let numbers = [1, 2, 3, 4, 5]; /// @@ -1414,8 +1438,8 @@ fn any(&mut self, mut f: F) -> bool where /// /// `find()` takes a closure that returns `true` or `false`. It applies /// this closure to each element of the iterator, and if any of them return - /// `true`, then `find()` returns `Some(element)`. If they all return - /// `false`, it returns `None`. + /// `true`, then `find()` returns [`Some(element)`]. If they all return + /// `false`, it returns [`None`]. /// /// `find()` is short-circuiting; in other words, it will stop processing /// as soon as the closure returns `true`. @@ -1425,6 +1449,9 @@ fn any(&mut self, mut f: F) -> bool where /// argument is a double reference. You can see this effect in the /// examples below, with `&&x`. /// + /// [`Some(element)`]: ../../std/option/enum.Option.html#variant.Some + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -1465,8 +1492,8 @@ fn find

(&mut self, mut predicate: P) -> Option where /// /// `position()` takes a closure that returns `true` or `false`. It applies /// this closure to each element of the iterator, and if one of them - /// returns `true`, then `position()` returns `Some(index)`. If all of - /// them return `false`, it returns `None`. + /// returns `true`, then `position()` returns [`Some(index)`]. If all of + /// them return `false`, it returns [`None`]. /// /// `position()` is short-circuiting; in other words, it will stop /// processing as soon as it finds a `true`. @@ -1474,7 +1501,7 @@ fn find

(&mut self, mut predicate: P) -> Option where /// # Overflow Behavior /// /// The method does no guarding against overflows, so if there are more - /// than `usize::MAX` non-matching elements, it either produces the wrong + /// than [`usize::MAX`] non-matching elements, it either produces the wrong /// result or panics. If debug assertions are enabled, a panic is /// guaranteed. /// @@ -1483,6 +1510,10 @@ fn find

(&mut self, mut predicate: P) -> Option where /// This function might panic if the iterator has more than `usize::MAX` /// non-matching elements. /// + /// [`Some(index)`]: ../../std/option/enum.Option.html#variant.Some + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// [`usize::MAX`]: ../../std/usize/constant.MAX.html + /// /// # Examples /// /// Basic usage: @@ -1528,11 +1559,14 @@ fn position

(&mut self, mut predicate: P) -> Option where /// `rposition()` takes a closure that returns `true` or `false`. It applies /// this closure to each element of the iterator, starting from the end, /// and if one of them returns `true`, then `rposition()` returns - /// `Some(index)`. If all of them return `false`, it returns `None`. + /// [`Some(index)`]. If all of them return `false`, it returns [`None`]. /// /// `rposition()` is short-circuiting; in other words, it will stop /// processing as soon as it finds a `true`. /// + /// [`Some(index)`]: ../../std/option/enum.Option.html#variant.Some + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -1798,11 +1832,13 @@ fn unzip(self) -> (FromA, FromB) where (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 + /// /// # Examples /// /// Basic usage: @@ -1827,10 +1863,12 @@ fn cloned<'a, T: 'a>(self) -> Cloned /// Repeats an iterator endlessly. /// - /// Instead of stopping at `None`, the iterator will instead start again, + /// Instead of stopping at [`None`], the iterator will instead start again, /// from the beginning. After iterating again, it will start at the /// beginning again. And again. And again. Forever. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -1862,7 +1900,7 @@ fn cycle(self) -> Cycle where Self: Sized + Clone { /// /// # Panics /// - /// When calling `sum` and a primitive integer type is being returned, this + /// When calling `sum()` and a primitive integer type is being returned, this /// method will panic if the computation overflows and debug assertions are /// enabled. /// @@ -1890,7 +1928,7 @@ fn sum(self) -> S /// /// # Panics /// - /// When calling `product` and a primitive integer type is being returned, + /// When calling `product()` and a primitive integer type is being returned, /// method will panic if the computation overflows and debug assertions are /// enabled. ///