Merge #539

539: Refine intra-doc links r=jswrenn a=tranzystorek-io

A few changes to make documenting code with links simpler and more uniform.

Highlights:

- Make some common stdlib traits into links, e.g. `IntoIterator`
- Add links to docs for free functions
- Use module paths uniformly in links (instead of html paths)
- Link to `slice::sort*` methods in docs for sorting functions

Co-authored-by: Marcin Puc <marcin.e.puc@gmail.com>

src/adaptors/mod.rs

@@ -35,7 +35,7 @@ pub struct Interleave<I, J> {
 
 /// Create an iterator that interleaves elements in `i` and `j`.
 ///
-/// `IntoIterator` enabled version of `i.interleave(j)`.
+/// [`IntoIterator`] enabled version of `i.interleave(j)`.
 ///
 /// See [`.interleave()`](crate::Itertools::interleave) for more information.
 pub fn interleave<I, J>(i: I, j: J) -> Interleave<<I as IntoIterator>::IntoIter, <J as IntoIterator>::IntoIter>
@@ -492,7 +492,7 @@ pub type Merge<I, J> = MergeBy<I, J, MergeLte>;
 
 /// Create an iterator that merges elements in `i` and `j`.
 ///
-/// `IntoIterator` enabled version of `i.merge(j)`.
+/// [`IntoIterator`] enabled version of [`Itertools::merge`](crate::Itertools::merge).
 ///
 /// ```
 /// use itertools::merge;

src/combinations.rs

@@ -48,9 +48,7 @@ impl<I: Iterator> Combinations<I> {
     pub fn k(&self) -> usize { self.indices.len() }
 
     /// Returns the (current) length of the pool from which combination elements are
-    /// selected. This value can change between invocations of [`next`].
-    ///
-    /// [`next`]: #method.next
+    /// selected. This value can change between invocations of [`next`](Combinations::next).
     #[inline]
     pub fn n(&self) -> usize { self.pool.len() }
 

src/concat_impl.rs

@@ -1,8 +1,8 @@
 use crate::Itertools;
 
-/// Combine all an iterator's elements into one element by using `Extend`.
+/// Combine all an iterator's elements into one element by using [`Extend`].
 ///
-/// `IntoIterator`-enabled version of `.concat()`
+/// [`IntoIterator`]-enabled version of [`Itertools::concat`].
 ///
 /// This combinator will extend the first item with each of the rest of the
 /// items of the iterator. If the iterator is empty, the default value of

src/diff.rs

@@ -26,7 +26,7 @@ pub enum Diff<I, J>
 }
 
 /// Compares every element yielded by both `i` and `j` with the given function in lock-step and
-/// returns a `Diff` which describes how `j` differs from `i`.
+/// returns a [`Diff`] which describes how `j` differs from `i`.
 ///
 /// If the number of elements yielded by `j` is less than the number of elements yielded by `i`,
 /// the number of `j` elements yielded will be returned along with `i`'s remaining elements as

src/duplicates_impl.rs

@@ -176,7 +176,7 @@ mod private {
 
 /// An iterator adapter to filter for duplicate elements.
 ///
-/// See [`.duplicates_by()`](../trait.Itertools.html#method.duplicates_by) for more information.
+/// See [`.duplicates_by()`](crate::Itertools::duplicates_by) for more information.
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub type DuplicatesBy<I, V, F> = private::DuplicatesBy<I, V, private::ByFn<F>>;
 
@@ -192,7 +192,7 @@ where
 
 /// An iterator adapter to filter out duplicate elements.
 ///
-/// See [`.duplicates()`](../trait.Itertools.html#method.duplicates) for more information.
+/// See [`.duplicates()`](crate::Itertools::duplicates) for more information.
 pub type Duplicates<I> = private::DuplicatesBy<I, <I as Iterator>::Item, private::ById>;
 
 /// Create a new `Duplicates` iterator.

src/either_or_both.rs

@@ -25,7 +25,7 @@ impl<A, B> EitherOrBoth<A, B> {
     }
 
     /// If Left, return true otherwise, return false.
-    /// Exclusive version of [`has_left`](Self::has_left).
+    /// Exclusive version of [`has_left`](EitherOrBoth::has_left).
     pub fn is_left(&self) -> bool {
         match *self {
             Left(_) => true,
@@ -34,7 +34,7 @@ impl<A, B> EitherOrBoth<A, B> {
     }
 
     /// If Right, return true otherwise, return false.
-    /// Exclusive version of [`has_right`](Self::has_right).
+    /// Exclusive version of [`has_right`](EitherOrBoth::has_right).
     pub fn is_right(&self) -> bool {
         match *self {
             Right(_) => true,

src/free.rs

@@ -1,6 +1,6 @@
 //! Free functions that create iterator adaptors or call iterator methods.
 //!
-//! The benefit of free functions is that they accept any `IntoIterator` as
+//! The benefit of free functions is that they accept any [`IntoIterator`] as
 //! argument, so the resulting code may be easier to read.
 
 #[cfg(feature = "use_alloc")]
@@ -37,7 +37,7 @@ pub use crate::rciter_impl::rciter;
 
 /// Iterate `iterable` with a running index.
 ///
-/// `IntoIterator` enabled version of `.enumerate()`.
+/// [`IntoIterator`] enabled version of [`Iterator::enumerate`].
 ///
 /// ```
 /// use itertools::enumerate;
@@ -54,7 +54,7 @@ pub fn enumerate<I>(iterable: I) -> iter::Enumerate<I::IntoIter>
 
 /// Iterate `iterable` in reverse.
 ///
-/// `IntoIterator` enabled version of `.rev()`.
+/// [`IntoIterator`] enabled version of [`Iterator::rev`].
 ///
 /// ```
 /// use itertools::rev;
@@ -72,7 +72,7 @@ pub fn rev<I>(iterable: I) -> iter::Rev<I::IntoIter>
 
 /// Iterate `i` and `j` in lock step.
 ///
-/// `IntoIterator` enabled version of `i.zip(j)`.
+/// [`IntoIterator`] enabled version of [`Iterator::zip`].
 ///
 /// ```
 /// use itertools::zip;
@@ -91,7 +91,7 @@ pub fn zip<I, J>(i: I, j: J) -> Zip<I::IntoIter, J::IntoIter>
 
 /// Create an iterator that first iterates `i` and then `j`.
 ///
-/// `IntoIterator` enabled version of `i.chain(j)`.
+/// [`IntoIterator`] enabled version of [`Iterator::chain`].
 ///
 /// ```
 /// use itertools::chain;
@@ -109,7 +109,7 @@ pub fn chain<I, J>(i: I, j: J) -> iter::Chain<<I as IntoIterator>::IntoIter, <J
 
 /// Create an iterator that clones each element from &T to T
 ///
-/// `IntoIterator` enabled version of `i.cloned()`.
+/// [`IntoIterator`] enabled version of [`Iterator::cloned`].
 ///
 /// ```
 /// use itertools::cloned;
@@ -125,7 +125,7 @@ pub fn cloned<'a, I, T: 'a>(iterable: I) -> iter::Cloned<I::IntoIter>
 
 /// Perform a fold operation over the iterable.
 ///
-/// `IntoIterator` enabled version of `i.fold(init, f)`
+/// [`IntoIterator`] enabled version of [`Iterator::fold`].
 ///
 /// ```
 /// use itertools::fold;
@@ -141,7 +141,7 @@ pub fn fold<I, B, F>(iterable: I, init: B, f: F) -> B
 
 /// Test whether the predicate holds for all elements in the iterable.
 ///
-/// `IntoIterator` enabled version of `i.all(f)`
+/// [`IntoIterator`] enabled version of [`Iterator::all`].
 ///
 /// ```
 /// use itertools::all;
@@ -157,7 +157,7 @@ pub fn all<I, F>(iterable: I, f: F) -> bool
 
 /// Test whether the predicate holds for any elements in the iterable.
 ///
-/// `IntoIterator` enabled version of `i.any(f)`
+/// [`IntoIterator`] enabled version of [`Iterator::any`].
 ///
 /// ```
 /// use itertools::any;
@@ -173,7 +173,7 @@ pub fn any<I, F>(iterable: I, f: F) -> bool
 
 /// Return the maximum value of the iterable.
 ///
-/// `IntoIterator` enabled version of `i.max()`.
+/// [`IntoIterator`] enabled version of [`Iterator::max`].
 ///
 /// ```
 /// use itertools::max;
@@ -189,7 +189,7 @@ pub fn max<I>(iterable: I) -> Option<I::Item>
 
 /// Return the minimum value of the iterable.
 ///
-/// `IntoIterator` enabled version of `i.min()`.
+/// [`IntoIterator`] enabled version of [`Iterator::min`].
 ///
 /// ```
 /// use itertools::min;
@@ -206,7 +206,7 @@ pub fn min<I>(iterable: I) -> Option<I::Item>
 
 /// Combine all iterator elements into one String, seperated by `sep`.
 ///
-/// `IntoIterator` enabled version of `iterable.join(sep)`.
+/// [`IntoIterator`] enabled version of [`Itertools::join`].
 ///
 /// ```
 /// use itertools::join;
@@ -223,9 +223,7 @@ pub fn join<I>(iterable: I, sep: &str) -> String
 
 /// Sort all iterator elements into a new iterator in ascending order.
 ///
-/// `IntoIterator` enabled version of [`iterable.sorted()`][1].
-///
-/// [1]: crate::Itertools::sorted
+/// [`IntoIterator`] enabled version of [`Itertools::sorted`].
 ///
 /// ```
 /// use itertools::sorted;

src/groupbylazy.rs

@@ -279,7 +279,7 @@ impl<K, I, F> GroupInner<K, I, F>
 /// no allocations. It needs allocations only if several group iterators
 /// are alive at the same time.
 ///
-/// This type implements `IntoIterator` (it is **not** an iterator
+/// This type implements [`IntoIterator`] (it is **not** an iterator
 /// itself), because the group iterators need to borrow from this
 /// value. It should be stored in a local variable or temporary and
 /// iterated.
@@ -453,7 +453,7 @@ pub fn new_chunks<J>(iter: J, size: usize) -> IntoChunks<J::IntoIter>
 /// `IntoChunks` behaves just like `GroupBy`: it is iterable, and
 /// it only buffers if several chunk iterators are alive at the same time.
 ///
-/// This type implements `IntoIterator` (it is **not** an iterator
+/// This type implements [`IntoIterator`] (it is **not** an iterator
 /// itself), because the chunk iterators need to borrow from this
 /// value. It should be stored in a local variable or temporary and
 /// iterated.

src/grouping_map.rs

@@ -7,7 +7,7 @@ use std::hash::Hash;
 use std::iter::Iterator;
 use std::ops::{Add, Mul};
 
-/// A wrapper to allow for an easy [`into_grouping_map_by`](../trait.Itertools.html#method.into_grouping_map_by)
+/// A wrapper to allow for an easy [`into_grouping_map_by`](crate::Itertools::into_grouping_map_by)
 #[derive(Clone, Debug)]
 pub struct MapForGrouping<I, F>(I, F);
 
@@ -38,7 +38,7 @@ pub fn new<I, K, V>(iter: I) -> GroupingMap<I>
 
 /// `GroupingMapBy` is an intermediate struct for efficient group-and-fold operations.
 /// 
-/// See [`GroupingMap`](./struct.GroupingMap.html) for more informations.
+/// See [`GroupingMap`] for more informations.
 #[must_use = "GroupingMapBy is lazy and do nothing unless consumed"]
 pub type GroupingMapBy<I, F> = GroupingMap<MapForGrouping<I, F>>;
 
@@ -377,7 +377,7 @@ impl<I, K, V> GroupingMap<I>
     /// If several elements are equally maximum, the last element is picked.
     /// If several elements are equally minimum, the first element is picked.
     /// 
-    /// See [.minmax()](../trait.Itertools.html#method.minmax) for the non-grouping version.
+    /// See [.minmax()](crate::Itertools::minmax) for the non-grouping version.
     /// 
     /// Differences from the non grouping version:
     /// - It never produces a `MinMaxResult::NoElements`