Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use intra-doc links in core/src/iter when possible #76867

Merged
merged 3 commits into from
Sep 21, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 29 additions & 47 deletions library/core/src/iter/sources.rs
Original file line number Diff line number Diff line change
@@ -5,9 +5,7 @@ use super::{FusedIterator, TrustedLen};

/// An iterator that repeats an element endlessly.
///
/// This `struct` is created by the [`repeat`] function. See its documentation for more.
///
/// [`repeat`]: fn.repeat.html
/// This `struct` is created by the [`repeat()`] function. See its documentation for more.
#[derive(Clone, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Repeat<A> {
@@ -47,15 +45,11 @@ unsafe impl<A: Clone> TrustedLen for Repeat<A> {}
/// The `repeat()` function repeats a single value over and over again.
///
/// Infinite iterators like `repeat()` are often used with adapters like
/// [`take`], in order to make them finite.
///
/// [`take`]: trait.Iterator.html#method.take
/// [`Iterator::take()`], in order to make them finite.
///
/// If the element type of the iterator you need does not implement `Clone`,
/// or if you do not want to keep the repeated element in memory, you can
/// instead use the [`repeat_with`] function.
///
/// [`repeat_with`]: fn.repeat_with.html
/// instead use the [`repeat_with()`] function.
///
/// # Examples
///
@@ -77,7 +71,7 @@ unsafe impl<A: Clone> TrustedLen for Repeat<A> {}
/// assert_eq!(Some(4), fours.next());
/// ```
///
/// Going finite with [`take`]:
/// Going finite with [`Iterator::take()`]:
///
/// ```
/// use std::iter;
@@ -102,10 +96,8 @@ pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
/// An iterator that repeats elements of type `A` endlessly by
/// applying the provided closure `F: FnMut() -> A`.
///
/// This `struct` is created by the [`repeat_with`] function.
/// This `struct` is created by the [`repeat_with()`] function.
/// See its documentation for more.
///
/// [`repeat_with`]: fn.repeat_with.html
#[derive(Copy, Clone, Debug)]
#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
pub struct RepeatWith<F> {
@@ -139,20 +131,18 @@ unsafe impl<A, F: FnMut() -> A> TrustedLen for RepeatWith<F> {}
/// The `repeat_with()` function calls the repeater over and over again.
///
/// Infinite iterators like `repeat_with()` are often used with adapters like
/// [`take`], in order to make them finite.
///
/// [`take`]: trait.Iterator.html#method.take
/// [`Iterator::take()`], in order to make them finite.
///
/// If the element type of the iterator you need implements `Clone`, and
/// If the element type of the iterator you need implements [`Clone`], and
/// it is OK to keep the source element in memory, you should instead use
/// the [`repeat`] function.
///
/// [`repeat`]: fn.repeat.html
/// the [`repeat()`] function.
///
/// An iterator produced by `repeat_with()` is not a `DoubleEndedIterator`.
/// If you need `repeat_with()` to return a `DoubleEndedIterator`,
/// An iterator produced by `repeat_with()` is not a [`DoubleEndedIterator`].
/// If you need `repeat_with()` to return a [`DoubleEndedIterator`],
/// please open a GitHub issue explaining your use case.
///
/// [`DoubleEndedIterator`]: crate::iter::DoubleEndedIterator
///
/// # Examples
///
/// Basic usage:
@@ -201,9 +191,7 @@ pub fn repeat_with<A, F: FnMut() -> A>(repeater: F) -> RepeatWith<F> {

/// An iterator that yields nothing.
///
/// This `struct` is created by the [`empty`] function. See its documentation for more.
///
/// [`empty`]: fn.empty.html
/// This `struct` is created by the [`empty()`] function. See its documentation for more.
#[stable(feature = "iter_empty", since = "1.2.0")]
pub struct Empty<T>(marker::PhantomData<T>);

@@ -292,9 +280,7 @@ pub const fn empty<T>() -> Empty<T> {

/// 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
/// This `struct` is created by the [`once()`] function. See its documentation for more.
#[derive(Clone, Debug)]
#[stable(feature = "iter_once", since = "1.2.0")]
pub struct Once<T> {
@@ -336,12 +322,12 @@ impl<T> FusedIterator for Once<T> {}

/// 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()`]: Iterator::chain
///
/// # Examples
///
@@ -393,10 +379,8 @@ pub fn once<T>(value: T) -> Once<T> {
/// An iterator that yields a single element of type `A` by
/// applying the provided closure `F: FnOnce() -> A`.
///
/// This `struct` is created by the [`once_with`] function.
/// This `struct` is created by the [`once_with()`] function.
Copy link
Contributor

@pickfire pickfire Sep 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// This `struct` is created by the [`once_with()`] function.
/// This `struct` is created by [`iter::once_with()`].

Based on #76816 comments

/// See its documentation for more.
///
/// [`once_with`]: fn.once_with.html
#[derive(Clone, Debug)]
#[stable(feature = "iter_once_with", since = "1.43.0")]
pub struct OnceWith<F> {
@@ -442,15 +426,14 @@ unsafe impl<A, F: FnOnce() -> A> TrustedLen for OnceWith<F> {}
/// Creates an iterator that lazily generates a value exactly once by invoking
/// the provided closure.
///
/// This is commonly used to adapt a single value generator into a [`chain`] of
/// This is commonly used to adapt a single value generator 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.
///
/// Unlike [`once`], this function will lazily generate the value on request.
/// Unlike [`once()`], this function will lazily generate the value on request.
///
/// [`once`]: fn.once.html
/// [`chain`]: trait.Iterator.html#method.chain
/// [`chain()`]: Iterator::chain
///
/// # Examples
///
@@ -505,17 +488,16 @@ pub fn once_with<A, F: FnOnce() -> A>(gen: F) -> OnceWith<F> {
///
/// This allows creating a custom iterator with any behavior
/// without using the more verbose syntax of creating a dedicated type
/// and implementing the `Iterator` trait for it.
/// and implementing the [`Iterator`] trait for it.
///
/// Note that the `FromFn` iterator doesn’t make assumptions about the behavior of the closure,
/// and therefore conservatively does not implement [`FusedIterator`],
/// or override [`Iterator::size_hint`] from its default `(0, None)`.
///
/// [`FusedIterator`]: trait.FusedIterator.html
/// [`Iterator::size_hint`]: trait.Iterator.html#method.size_hint
/// or override [`Iterator::size_hint()`] from its default `(0, None)`.
///
/// The closure can use captures and its environment to track state across iterations. Depending on
/// how the iterator is used, this may require specifying the `move` keyword on the closure.
/// how the iterator is used, this may require specifying the [`move`] keyword on the closure.
///
/// [`move`]: ../../std/keyword.move.html
///
/// # Examples
///
@@ -549,10 +531,10 @@ where

/// An iterator where each iteration calls the provided closure `F: FnMut() -> Option<T>`.
///
/// This `struct` is created by the [`iter::from_fn`] function.
/// This `struct` is created by the [`iter::from_fn()`] function.
/// See its documentation for more.
///
/// [`iter::from_fn`]: fn.from_fn.html
/// [`iter::from_fn()`]: from_fn
#[derive(Clone)]
#[stable(feature = "iter_from_fn", since = "1.34.0")]
pub struct FromFn<F>(F);
@@ -601,10 +583,10 @@ where

/// An new iterator where each successive item is computed based on the preceding one.
///
/// This `struct` is created by the [`successors`] function.
/// This `struct` is created by the [`iter::successors()`] function.
/// See its documentation for more.
///
/// [`successors`]: fn.successors.html
/// [`iter::successors()`]: successors
#[derive(Clone)]
#[stable(feature = "iter_successors", since = "1.34.0")]
pub struct Successors<T, F> {
46 changes: 22 additions & 24 deletions library/core/src/iter/traits/accum.rs
Original file line number Diff line number Diff line change
@@ -4,14 +4,13 @@ use crate::ops::{Add, Mul};

/// 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`]: #tymethod.sum
/// [`FromIterator`]: crate::iter::FromIterator
/// [`Iterator::sum`]: crate::iter::Iterator::sum
/// [`sum()`]: Sum::sum
/// [`FromIterator`]: iter::FromIterator
#[stable(feature = "iter_arith_traits", since = "1.12.0")]
pub trait Sum<A = Self>: Sized {
/// Method which takes an iterator and generates `Self` from the elements by
@@ -23,14 +22,13 @@ pub trait Sum<A = Self>: 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`]: #tymethod.product
/// [`FromIterator`]: crate::iter::FromIterator
/// [`Iterator::product`]: crate::iter::Iterator::product
/// [`product()`]: Product::product
/// [`FromIterator`]: iter::FromIterator
#[stable(feature = "iter_arith_traits", since = "1.12.0")]
pub trait Product<A = Self>: Sized {
/// Method which takes an iterator and generates `Self` from the elements by
@@ -120,9 +118,9 @@ impl<T, U, E> Sum<Result<U, E>> for Result<T, E>
where
T: Sum<U>,
{
/// Takes each element in the `Iterator`: if it is an `Err`, no further
/// elements are taken, and the `Err` is returned. Should no `Err` occur,
/// the sum of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is an [`Err`], no further
/// elements are taken, and the [`Err`] is returned. Should no [`Err`]
/// occur, the sum of all elements is returned.
///
/// # Examples
///
@@ -150,9 +148,9 @@ impl<T, U, E> Product<Result<U, E>> for Result<T, E>
where
T: Product<U>,
{
/// Takes each element in the `Iterator`: if it is an `Err`, no further
/// elements are taken, and the `Err` is returned. Should no `Err` occur,
/// the product of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is an [`Err`], no further
/// elements are taken, and the [`Err`] is returned. Should no [`Err`]
/// occur, the product of all elements is returned.
fn product<I>(iter: I) -> Result<T, E>
where
I: Iterator<Item = Result<U, E>>,
@@ -166,9 +164,9 @@ impl<T, U> Sum<Option<U>> for Option<T>
where
T: Sum<U>,
{
/// Takes each element in the `Iterator`: if it is a `None`, no further
/// elements are taken, and the `None` is returned. Should no `None` occur,
/// the sum of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is a [`None`], no further
/// elements are taken, and the [`None`] is returned. Should no [`None`]
/// occur, the sum of all elements is returned.
///
/// # Examples
///
@@ -193,9 +191,9 @@ impl<T, U> Product<Option<U>> for Option<T>
where
T: Product<U>,
{
/// Takes each element in the `Iterator`: if it is a `None`, no further
/// elements are taken, and the `None` is returned. Should no `None` occur,
/// the product of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is a [`None`], no further
/// elements are taken, and the [`None`] is returned. Should no [`None`]
/// occur, the product of all elements is returned.
fn product<I>(iter: I) -> Option<T>
where
I: Iterator<Item = Option<U>>,
20 changes: 6 additions & 14 deletions library/core/src/iter/traits/collect.rs
Original file line number Diff line number Diff line change
@@ -1,21 +1,15 @@
/// Conversion from an `Iterator`.
/// Conversion from an [`Iterator`].
///
/// By implementing `FromIterator` for a type, you define how it will be
/// 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::from_iter()`] is rarely called explicitly, and is instead
/// used through [`Iterator::collect()`] method. See [`Iterator::collect()`]'s
/// documentation for more examples.
///
/// [`from_iter`]: #tymethod.from_iter
/// [`Iterator`]: trait.Iterator.html
/// [`collect`]: trait.Iterator.html#method.collect
///
/// See also: [`IntoIterator`].
///
/// [`IntoIterator`]: trait.IntoIterator.html
///
/// # Examples
///
/// Basic usage:
@@ -30,7 +24,7 @@
/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
/// ```
///
/// Using [`collect`] to implicitly use `FromIterator`:
/// Using [`Iterator::collect()`] to implicitly use `FromIterator`:
///
/// ```
/// let five_fives = std::iter::repeat(5).take(5);
@@ -119,7 +113,7 @@ pub trait FromIterator<A>: Sized {
fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self;
}

/// Conversion into an `Iterator`.
/// Conversion into an [`Iterator`].
///
/// By implementing `IntoIterator` for a type, you define how it will be
/// converted to an iterator. This is common for types which describe a
@@ -130,8 +124,6 @@ pub trait FromIterator<A>: Sized {
///
/// See also: [`FromIterator`].
///
/// [`FromIterator`]: trait.FromIterator.html
///
/// # Examples
///
/// Basic usage:
@@ -326,7 +318,7 @@ pub trait Extend<A> {
/// As this is the only required method for this trait, the [trait-level] docs
/// contain more details.
///
/// [trait-level]: trait.Extend.html
/// [trait-level]: Extend
///
/// # Examples
///
Loading