From 302de36c8f647bd394d75f1ab28255f00c8d703a Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 13 Oct 2015 13:49:53 -0400 Subject: [PATCH] Properly link up iterator documentation Due to the way iterators work, the std::iter module is chock full of structs that you, humble Rust programmer, will never actually use. However, they have URLs, and therefore get linked to, because they are real structs that do exist. So, rather than just have a tiny sentence about each one of them, this patch adds links back to the functions and methods on Iterator which actually create the structs, where helpful documentation already exists. --- src/libcore/iter.rs | 157 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 137 insertions(+), 20 deletions(-) diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index 2f12579d67411..d54817f5201e1 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -1618,7 +1618,13 @@ impl ExactSizeIterator for Map where impl ExactSizeIterator for Zip where A: ExactSizeIterator, B: ExactSizeIterator {} -/// An double-ended iterator with the direction inverted +/// An double-ended iterator with the direction inverted. +/// +/// This `struct` is created by the [`rev()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`rev()`]: trait.Iterator.html#method.rev +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1642,7 +1648,13 @@ impl DoubleEndedIterator for Rev where I: DoubleEndedIterator { fn next_back(&mut self) -> Option<::Item> { self.iter.next() } } -/// An iterator that clones the elements of an underlying iterator +/// An iterator that clones the elements of an underlying iterator. +/// +/// This `struct` is created by the [`cloned()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`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"] #[derive(Clone)] @@ -1679,7 +1691,13 @@ impl<'a, I, T: 'a> ExactSizeIterator for Cloned where I: ExactSizeIterator, T: Clone {} -/// An iterator that repeats endlessly +/// An iterator that repeats endlessly. +/// +/// This `struct` is created by the [`cycle()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`cycle()`]: trait.Iterator.html#method.cycle +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1711,7 +1729,13 @@ impl Iterator for Cycle where I: Clone + Iterator { } } -/// An iterator that strings two iterators together +/// An iterator that strings two iterators together. +/// +/// This `struct` is created by the [`chain()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`chain()`]: trait.Iterator.html#method.chain +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1849,7 +1873,13 @@ impl DoubleEndedIterator for Chain where } } -/// An iterator that iterates two other iterators simultaneously +/// An iterator that iterates two other iterators simultaneously. +/// +/// This `struct` is created by the [`zip()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`zip()`]: trait.Iterator.html#method.zip +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -1915,7 +1945,13 @@ impl DoubleEndedIterator for Zip where } } -/// An iterator that maps the values of `iter` with `f` +/// An iterator that maps the values of `iter` with `f`. +/// +/// This `struct` is created by the [`map()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`map()`]: trait.Iterator.html#method.map +/// [`Iterator`]: trait.Iterator.html #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] #[derive(Clone)] @@ -1949,7 +1985,13 @@ impl DoubleEndedIterator for Map where } } -/// An iterator that filters the elements of `iter` with `predicate` +/// An iterator that filters the elements of `iter` with `predicate`. +/// +/// This `struct` is created by the [`filter()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`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")] #[derive(Clone)] @@ -1994,7 +2036,13 @@ impl DoubleEndedIterator for Filter } } -/// An iterator that uses `f` to both filter and map elements from `iter` +/// 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 +/// documentation for more. +/// +/// [`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")] #[derive(Clone)] @@ -2041,7 +2089,13 @@ impl DoubleEndedIterator for FilterMap } } -/// An iterator that yields the current count and the element during iteration +/// An iterator that yields the current count and the element during iteration. +/// +/// This `struct` is created by the [`enumerate()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`enumerate()`]: trait.Iterator.html#method.enumerate +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -2108,7 +2162,14 @@ impl DoubleEndedIterator for Enumerate where } } -/// An iterator with a `peek()` that returns an optional reference to the next element. +/// 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 +/// documentation for more. +/// +/// [`peekable()`]: trait.Iterator.html#method.peekable +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -2190,7 +2251,13 @@ impl Peekable { } } -/// An iterator that rejects elements while `predicate` is true +/// An iterator that rejects elements while `predicate` is true. +/// +/// This `struct` is created by the [`skip_while()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`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")] #[derive(Clone)] @@ -2224,7 +2291,13 @@ impl Iterator for SkipWhile } } -/// An iterator that only accepts elements while `predicate` is true +/// An iterator that only accepts elements while `predicate` is true. +/// +/// This `struct` is created by the [`take_while()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`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")] #[derive(Clone)] @@ -2264,6 +2337,12 @@ impl Iterator for TakeWhile } /// An iterator that skips over `n` elements of `iter`. +/// +/// This `struct` is created by the [`skip()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`skip()`]: trait.Iterator.html#method.skip +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -2338,6 +2417,12 @@ impl Iterator for Skip where I: Iterator { impl ExactSizeIterator for Skip where I: ExactSizeIterator {} /// An iterator that only iterates over the first `n` iterations of `iter`. +/// +/// This `struct` is created by the [`take()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`take()`]: trait.Iterator.html#method.take +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -2393,7 +2478,13 @@ impl Iterator for Take where I: Iterator{ impl ExactSizeIterator for Take where I: ExactSizeIterator {} -/// An iterator to maintain state while iterating another iterator +/// An iterator to maintain state while iterating another iterator. +/// +/// This `struct` is created by the [`scan()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`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")] #[derive(Clone)] @@ -2422,9 +2513,14 @@ impl Iterator for Scan where } } -/// An iterator that maps each element to an iterator, -/// and yields the elements of the produced iterators +/// 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 +/// documentation for more. +/// +/// [`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")] #[derive(Clone)] @@ -2493,8 +2589,11 @@ impl DoubleEndedIterator for FlatMap wher /// An iterator that yields `None` forever after the underlying iterator /// yields `None` once. /// -/// These can be created through -/// [`iter.fuse()`](trait.Iterator.html#method.fuse). +/// This `struct` is created by the [`fuse()`] method on [`Iterator`]. See its +/// documentation for more. +/// +/// [`fuse()`]: trait.Iterator.html#method.fuse +/// [`Iterator`]: trait.Iterator.html #[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] @@ -2574,8 +2673,14 @@ impl DoubleEndedIterator for Fuse where I: DoubleEndedIterator { #[stable(feature = "rust1", since = "1.0.0")] impl ExactSizeIterator for Fuse where I: ExactSizeIterator {} -/// An iterator that calls a function with a reference to each -/// element before yielding it. +/// 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 +/// documentation for more. +/// +/// [`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")] #[derive(Clone)] @@ -3009,7 +3114,11 @@ impl Iterator for ops::RangeFrom where } } -/// An iterator that repeats an element endlessly +/// An iterator that repeats an element endlessly. +/// +/// This `struct` is created by the [`repeat()`] function. See its documentation for more. +/// +/// [`repeat()`]: fn.repeat.html #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] pub struct Repeat { @@ -3040,6 +3149,10 @@ pub fn repeat(elt: T) -> Repeat { } /// An iterator that yields nothing. +/// +/// This `struct` is created by the [`empty()`] function. See its documentation for more. +/// +/// [`empty()`]: fn.empty.html #[stable(feature = "iter_empty", since = "1.2.0")] pub struct Empty(marker::PhantomData); @@ -3095,6 +3208,10 @@ 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. +/// +/// [`once()`]: fn.once.html #[derive(Clone)] #[stable(feature = "iter_once", since = "1.2.0")] pub struct Once {