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.

Sign up for GitHub

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

Jump to bottom

Use intra-doc links in core::iter module #74300

Merged
merged 8 commits into from
Jul 18, 2020
Merged

Use intra-doc links in core::iter module #74300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
91738d8
Use intra-doc link on Iterator page
tesuji Jul 13, 2020
53a1d6f
Intra doc for iter marker traits
tesuji Jul 13, 2020
69f43dd
Intra-doc for DoubleEndIterator
tesuji Jul 13, 2020
a7f067a
Intra-doc for iter Sum and Product traits
tesuji Jul 13, 2020
3fb3c0c
Remove unneeded link for Option
tesuji Jul 13, 2020
1a90ba7
Link Some(item)
tesuji Jul 14, 2020
67c1e89
Remove code span for impl
tesuji Jul 14, 2020
5ffdd7c
Deny intra_doc_link_resolution_failure in libcore
tesuji Jul 17, 2020
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
12 changes: 6 additions & 6 deletions src/libcore/iter/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,11 @@
//! ```
//!
//! An iterator has a method, [`next`], which when called, returns an
//! [`Option`]`<Item>`. [`next`] will return `Some(Item)` as long as there
//! [`Option`]`<Item>`. [`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
//! start returning `Some(Item)` again at some point (for example, see [`TryIter`]).
//! start returning [`Some(Item)`] again at some point (for example, see [`TryIter`]).
//!
//! [`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
Expand All @@ -53,9 +53,9 @@
//! more complex forms of processing. See the [Adapters](#adapters) section
//! below for more details.
//!
//! [`Some(Item)`]: Some
//! [`Iterator`]: trait.Iterator.html
//! [`next`]: trait.Iterator.html#tymethod.next
//! [`Option`]: ../../std/option/enum.Option.html
//! [`TryIter`]: ../../std/sync/mpsc/struct.TryIter.html
//!
//! # The three forms of iteration
Expand All @@ -72,9 +72,9 @@
//! # Implementing Iterator
//!
//! Creating an iterator of your own involves two steps: creating a `struct` to
//! hold the iterator's state, and then `impl`ementing [`Iterator`] for that
//! `struct`. This is why there are so many `struct`s in this module: there is
//! one for each iterator and iterator adapter.
//! hold the iterator's state, and then implementing [`Iterator`] for that `struct`.
//! This is why there are so many `struct`s in this module: there is one for
//! each iterator and iterator adapter.
//!
//! Let's make an iterator named `Counter` which counts from `1` to `5`:
//!
Expand Down
12 changes: 6 additions & 6 deletions src/libcore/iter/traits/accum.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ use crate::ops::{Add, Mul};
/// [`FromIterator`] this trait should rarely be called directly and instead
/// interacted with through [`Iterator::sum`].
///
/// [`sum`]: ../../std/iter/trait.Sum.html#tymethod.sum
/// [`FromIterator`]: ../../std/iter/trait.FromIterator.html
/// [`Iterator::sum`]: ../../std/iter/trait.Iterator.html#method.sum
/// [`sum`]: #tymethod.sum
Copy link
Contributor

Choose a reason for hiding this comment

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

Does this not have an equivalent?

Copy link
Contributor Author

@tesuji tesuji Jul 14, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

This fragment link is fine as the sum method referred belongs to Sum trait.

Copy link
Member

Choose a reason for hiding this comment

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

This is #51284, which is a project all on its own. If @lzutao checked that it works I'm fine with it.

Copy link
Member

Choose a reason for hiding this comment

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

Can this not be Sum::sum or Self::sum?

Copy link
Contributor Author

@tesuji tesuji Jul 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Is it documented in Intra RFC? That's new to me!

/// [`FromIterator`]: crate::iter::FromIterator
/// [`Iterator::sum`]: crate::iter::Iterator::sum
#[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
Expand All @@ -28,9 +28,9 @@ pub trait Sum<A = Self>: Sized {
/// [`FromIterator`] this trait should rarely be called directly and instead
/// interacted with through [`Iterator::product`].
///
/// [`product`]: ../../std/iter/trait.Product.html#tymethod.product
/// [`FromIterator`]: ../../std/iter/trait.FromIterator.html
/// [`Iterator::product`]: ../../std/iter/trait.Iterator.html#method.product
/// [`product`]: #tymethod.product
/// [`FromIterator`]: crate::iter::FromIterator
/// [`Iterator::product`]: crate::iter::Iterator::product
#[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
Expand Down
6 changes: 2 additions & 4 deletions src/libcore/iter/traits/double_ended.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,7 @@ pub trait DoubleEndedIterator: Iterator {
/// `nth_back()` will return [`None`] if `n` is greater than or equal to the length of the
/// iterator.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`nth`]: ../../std/iter/trait.Iterator.html#method.nth
/// [`nth`]: crate::iter::Iterator::nth
///
/// # Examples
///
Expand Down Expand Up @@ -274,8 +273,7 @@ pub trait DoubleEndedIterator: Iterator {
/// 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
/// [`Some(element)`]: Some
///
/// # Examples
///
Expand Down
77 changes: 21 additions & 56 deletions src/libcore/iter/traits/iterator.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,7 @@ pub trait Iterator {
/// 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
/// [`Some(Item)`]: Some
///
/// # Examples
///
Expand Down Expand Up @@ -160,9 +159,7 @@ 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
/// [`usize`]: type@usize
///
/// # Examples
///
Expand Down Expand Up @@ -214,8 +211,6 @@ pub trait Iterator {
/// called at least once even if the iterator does not have any elements.
///
/// [`next`]: #tymethod.next
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`Some`]: ../../std/option/enum.Option.html#variant.Some
///
/// # Overflow Behavior
///
Expand All @@ -229,7 +224,7 @@ pub trait Iterator {
/// This function might panic if the iterator has more than [`usize::MAX`]
/// elements.
///
/// [`usize::MAX`]: ../../std/usize/constant.MAX.html
/// [`usize::MAX`]: crate::usize::MAX
///
/// # Examples
///
Expand Down Expand Up @@ -263,8 +258,6 @@ pub trait Iterator {
/// 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:
Expand Down Expand Up @@ -303,8 +296,6 @@ pub trait Iterator {
/// `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:
Expand Down Expand Up @@ -537,9 +528,8 @@ pub trait Iterator {
/// assert_eq!((2, 'o'), zipper[2]);
/// ```
///
/// [`enumerate`]: trait.Iterator.html#method.enumerate
/// [`next`]: ../../std/iter/trait.Iterator.html#tymethod.next
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`enumerate`]: #method.enumerate
/// [`next`]: #tymethod.next
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>
Expand Down Expand Up @@ -568,7 +558,7 @@ pub trait Iterator {
/// more idiomatic to use [`for`] than `map()`.
///
/// [`for`]: ../../book/ch03-05-control-flow.html#looping-through-a-collection-with-for
/// [`FnMut`]: ../../std/ops/trait.FnMut.html
/// [`FnMut`]: crate::ops::FnMut
///
/// # Examples
///
Expand Down Expand Up @@ -777,9 +767,7 @@ pub trait Iterator {
/// assert_eq!(iter.next(), None);
/// ```
///
/// [`Option<T>`]: ../../std/option/enum.Option.html
/// [`Some`]: ../../std/option/enum.Option.html#variant.Some
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`Option<T>`]: Option
Copy link
Member

Choose a reason for hiding this comment

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

This is #62834. This is a good workaround in the meantime though.

Copy link
Contributor

Choose a reason for hiding this comment

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

But why not just use Option rather than Option<T>?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Option<T> seems to be clearer for beginners/first readers of Iterator.

Copy link
Contributor

Choose a reason for hiding this comment

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

We could use Option<T> in the book, but I don't think beginners get here easily.

#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>
Expand Down Expand Up @@ -812,8 +800,8 @@ pub trait Iterator {
/// The returned iterator might panic if the to-be-returned index would
/// overflow a [`usize`].
///
/// [`usize::MAX`]: ../../std/usize/constant.MAX.html
/// [`usize`]: ../../std/primitive.usize.html
/// [`usize`]: type@usize
/// [`usize::MAX`]: crate::usize::MAX
/// [`zip`]: #method.zip
///
/// # Examples
Expand Down Expand Up @@ -849,8 +837,8 @@ pub trait Iterator {
/// anything other than fetching the next value) of the [`next`] method
/// will occur.
///
/// [`peek`]: struct.Peekable.html#method.peek
/// [`next`]: ../../std/iter/trait.Iterator.html#tymethod.next
/// [`peek`]: crate::iter::Peekable::peek
/// [`next`]: #tymethod.next
///
/// # Examples
///
Expand Down Expand Up @@ -1116,8 +1104,6 @@ pub trait Iterator {
/// It is also not specified what this iterator returns after the first` None` is returned.
/// If you need fused iterator, use [`fuse`].
///
/// [`Some`]: ../../std/option/enum.Option.html#variant.Some
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`fuse`]: #method.fuse
#[inline]
#[unstable(feature = "iter_map_while", reason = "recently added", issue = "68537")]
Expand Down Expand Up @@ -1216,8 +1202,6 @@ pub trait Iterator {
/// iterator and the return value from the closure, an [`Option`], is
/// yielded by the iterator.
///
/// [`Option`]: ../../std/option/enum.Option.html
///
/// # Examples
///
/// Basic usage:
Expand Down Expand Up @@ -1366,8 +1350,7 @@ pub trait Iterator {
/// [`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
/// [`Some(T)`]: Some
Copy link
Member

Choose a reason for hiding this comment

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

I've seen this quite a few times now, maybe it would be a good feature for intra-doc links to add, same as #62834?

///
/// # Examples
///
Expand Down Expand Up @@ -1658,10 +1641,9 @@ pub trait Iterator {
/// assert_eq!(Ok(vec![1, 3]), result);
/// ```
///
/// [`iter`]: ../../std/iter/trait.Iterator.html#tymethod.next
/// [`iter`]: #tymethod.next
/// [`String`]: ../../std/string/struct.String.html
/// [`char`]: ../../std/primitive.char.html
/// [`Result`]: ../../std/result/enum.Result.html
/// [`char`]: type@char
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[must_use = "if you really need to exhaust the iterator, consider `.for_each(drop)` instead"]
Expand Down Expand Up @@ -2184,8 +2166,7 @@ pub trait Iterator {
/// 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
/// [`Some(element)`]: Some
///
/// # Examples
///
Expand Down Expand Up @@ -2331,9 +2312,8 @@ pub trait Iterator {
/// 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
/// [`Some(index)`]: Some
/// [`usize::MAX`]: crate::usize::MAX
///
/// # Examples
///
Expand Down Expand Up @@ -2394,8 +2374,7 @@ pub trait Iterator {
/// `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
/// [`Some(index)`]: Some
///
/// # Examples
///
Expand Down Expand Up @@ -2449,8 +2428,6 @@ pub trait Iterator {
/// If several elements are equally maximum, the last element is
/// returned. If the iterator is empty, [`None`] is returned.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
Expand All @@ -2477,8 +2454,6 @@ pub trait Iterator {
/// If several elements are equally minimum, the first element is
/// returned. If the iterator is empty, [`None`] is returned.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
Expand Down Expand Up @@ -2506,8 +2481,6 @@ pub trait Iterator {
/// If several elements are equally maximum, the last element is
/// returned. If the iterator is empty, [`None`] is returned.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -2541,8 +2514,6 @@ pub trait Iterator {
/// If several elements are equally maximum, the last element is
/// returned. If the iterator is empty, [`None`] is returned.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -2570,8 +2541,6 @@ pub trait Iterator {
/// If several elements are equally minimum, the first element is
/// returned. If the iterator is empty, [`None`] is returned.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -2605,8 +2574,6 @@ pub trait Iterator {
/// If several elements are equally minimum, the first element is
/// returned. If the iterator is empty, [`None`] is returned.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
Expand Down Expand Up @@ -2747,7 +2714,7 @@ pub trait Iterator {
/// 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`]: crate::clone::Clone::clone
///
/// # Examples
///
Expand Down Expand Up @@ -2779,8 +2746,6 @@ pub trait Iterator {
/// 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:
Expand Down Expand Up @@ -3233,7 +3198,7 @@ pub trait Iterator {
/// assert!(![0.0, 1.0, f32::NAN].iter().is_sorted_by(|a, b| a.partial_cmp(b)));
/// ```
///
/// [`is_sorted`]: trait.Iterator.html#method.is_sorted
/// [`is_sorted`]: #method.is_sorted
#[unstable(feature = "is_sorted", reason = "new API", issue = "53485")]
fn is_sorted_by<F>(mut self, mut compare: F) -> bool
where
Expand Down Expand Up @@ -3262,7 +3227,7 @@ pub trait Iterator {
/// the elements, as determined by `f`. Apart from that, it's equivalent to [`is_sorted`]; see
/// its documentation for more information.
///
/// [`is_sorted`]: trait.Iterator.html#method.is_sorted
/// [`is_sorted`]: #method.is_sorted
///
/// # Examples
///
Expand Down
10 changes: 4 additions & 6 deletions src/libcore/iter/traits/marker.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,8 @@
/// 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
/// [`Fuse`]: ../../std/iter/struct.Fuse.html
/// [`Iterator::fuse`]: crate::iter::Iterator::fuse
/// [`Fuse`]: crate::iter::Fuse
#[stable(feature = "fused", since = "1.26.0")]
#[rustc_unsafe_specialization_marker]
pub trait FusedIterator: Iterator {}
Expand All @@ -35,9 +34,8 @@ impl<I: FusedIterator + ?Sized> FusedIterator for &mut I {}
/// This trait must only be implemented when the contract is upheld.
/// 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
/// [`usize::MAX`]: crate::usize::MAX
/// [`.size_hint`]: crate::iter::Iterator::size_hint
#[unstable(feature = "trusted_len", issue = "37572")]
#[rustc_unsafe_specialization_marker]
pub unsafe trait TrustedLen: Iterator {}
Expand Down
1 change: 1 addition & 0 deletions src/libcore/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,7 @@
#![feature(slice_ptr_get)]
#![feature(no_niche)] // rust-lang/rust#68303
#![feature(unsafe_block_in_unsafe_fn)]
#![deny(intra_doc_link_resolution_failure)]
#![deny(unsafe_op_in_unsafe_fn)]

#[prelude_import]
Expand Down