Rollup merge of #59275 - regexident:docs-self, r=joshtriplett

Replaced self-reflective explicit types with clearer `Self` or `Self::…` in stdlib docs

Many docs examples use explicit types instead of the semantically more clear `Self`/`Self::…` aliases.

By using the latter it's clear that the value's type depends on either `Self`, or an associated type of `Self`, instead of some constant type. It's also more consistent (and I'd argue correct), as the current docs aren't really consistent in this, as can be seen from the diff.

This is a best effort PR, as I was basically going through the docs manually, looking for offending examples. I'm sure I missed a few. Gotta start somewhere.

src/libcore/cmp.rs

@@ -72,7 +72,7 @@
 /// }
 ///
 /// impl PartialEq for Book {
-///     fn eq(&self, other: &Book) -> bool {
+///     fn eq(&self, other: &Self) -> bool {
 ///         self.isbn == other.isbn
 ///     }
 /// }
@@ -233,7 +233,7 @@ fn ne(&self, other: &Rhs) -> bool { !self.eq(other) }
 ///     format: BookFormat,
 /// }
 /// impl PartialEq for Book {
-///     fn eq(&self, other: &Book) -> bool {
+///     fn eq(&self, other: &Self) -> bool {
 ///         self.isbn == other.isbn
 ///     }
 /// }
@@ -493,19 +493,19 @@ fn cmp(&self, other: &Reverse<T>) -> Ordering {
 /// }
 ///
 /// impl Ord for Person {
-///     fn cmp(&self, other: &Person) -> Ordering {
+///     fn cmp(&self, other: &Self) -> Ordering {
 ///         self.height.cmp(&other.height)
 ///     }
 /// }
 ///
 /// impl PartialOrd for Person {
-///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
+///     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
 ///         Some(self.cmp(other))
 ///     }
 /// }
 ///
 /// impl PartialEq for Person {
-///     fn eq(&self, other: &Person) -> bool {
+///     fn eq(&self, other: &Self) -> bool {
 ///         self.height == other.height
 ///     }
 /// }
@@ -691,13 +691,13 @@ fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> {
 /// }
 ///
 /// impl PartialOrd for Person {
-///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
+///     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
 ///         self.height.partial_cmp(&other.height)
 ///     }
 /// }
 ///
 /// impl PartialEq for Person {
-///     fn eq(&self, other: &Person) -> bool {
+///     fn eq(&self, other: &Self) -> bool {
 ///         self.height == other.height
 ///     }
 /// }

src/libcore/iter/mod.rs

@@ -101,7 +101,7 @@
 //!     type Item = usize;
 //!
 //!     // next() is the only required method
-//!     fn next(&mut self) -> Option<usize> {
+//!     fn next(&mut self) -> Option<Self::Item> {
 //!         // Increment our count. This is why we started at zero.
 //!         self.count += 1;
 //!

src/libcore/iter/traits/collect.rs

@@ -167,7 +167,7 @@ pub trait FromIterator<A>: Sized {
 /// // and we'll implement IntoIterator
 /// impl IntoIterator for MyCollection {
 ///     type Item = i32;
-///     type IntoIter = ::std::vec::IntoIter<i32>;
+///     type IntoIter = ::std::vec::IntoIter<Self::Item>;
 ///
 ///     fn into_iter(self) -> Self::IntoIter {
 ///         self.0.into_iter()

src/libcore/iter/traits/exact_size.rs

@@ -45,7 +45,7 @@
 /// # }
 /// # impl Iterator for Counter {
 /// #     type Item = usize;
-/// #     fn next(&mut self) -> Option<usize> {
+/// #     fn next(&mut self) -> Option<Self::Item> {
 /// #         self.count += 1;
 /// #         if self.count < 6 {
 /// #             Some(self.count)

src/libcore/ops/arith.rs

@@ -20,10 +20,10 @@
 /// }
 ///
 /// impl Add for Point {
-///     type Output = Point;
+///     type Output = Self;
 ///
-///     fn add(self, other: Point) -> Point {
-///         Point {
+///     fn add(self, other: Self) -> Self {
+///         Self {
 ///             x: self.x + other.x,
 ///             y: self.y + other.y,
 ///         }
@@ -50,10 +50,10 @@
 ///
 /// // Notice that the implementation uses the associated type `Output`.
 /// impl<T: Add<Output = T>> Add for Point<T> {
-///     type Output = Point<T>;
+///     type Output = Self;
 ///
-///     fn add(self, other: Point<T>) -> Point<T> {
-///         Point {
+///     fn add(self, other: Self) -> Self::Output {
+///         Self {
 ///             x: self.x + other.x,
 ///             y: self.y + other.y,
 ///         }
@@ -158,9 +158,9 @@ fn add(self, other: $t) -> $t { self + other }
 ///
 /// // Notice that the implementation uses the associated type `Output`.
 /// impl<T: Sub<Output = T>> Sub for Point<T> {
-///     type Output = Point<T>;
+///     type Output = Self;
 ///
-///     fn sub(self, other: Point<T>) -> Point<T> {
+///     fn sub(self, other: Self) -> Self::Output {
 ///         Point {
 ///             x: self.x - other.x,
 ///             y: self.y - other.y,
@@ -280,9 +280,9 @@ fn sub(self, other: $t) -> $t { self - other }
 /// struct Vector { value: Vec<usize> }
 ///
 /// impl Mul<Scalar> for Vector {
-///     type Output = Vector;
+///     type Output = Self;
 ///
-///     fn mul(self, rhs: Scalar) -> Vector {
+///     fn mul(self, rhs: Scalar) -> Self::Output {
 ///         Vector { value: self.value.iter().map(|v| v * rhs.value).collect() }
 ///     }
 /// }
@@ -364,7 +364,7 @@ fn mul(self, other: $t) -> $t { self * other }
 ///     // The division of rational numbers is a closed operation.
 ///     type Output = Self;
 ///
-///     fn div(self, rhs: Self) -> Self {
+///     fn div(self, rhs: Self) -> Self::Output {
 ///         if rhs.nominator == 0 {
 ///             panic!("Cannot divide by zero-valued `Rational`!");
 ///         }
@@ -404,9 +404,9 @@ fn mul(self, other: $t) -> $t { self * other }
 /// struct Vector { value: Vec<f32> }
 ///
 /// impl Div<Scalar> for Vector {
-///     type Output = Vector;
+///     type Output = Self;
 ///
-///     fn div(self, rhs: Scalar) -> Vector {
+///     fn div(self, rhs: Scalar) -> Self::Output {
 ///         Vector { value: self.value.iter().map(|v| v / rhs.value).collect() }
 ///     }
 /// }
@@ -485,9 +485,9 @@ fn div(self, other: $t) -> $t { self / other }
 /// }
 ///
 /// impl<'a, T> Rem<usize> for SplitSlice<'a, T> {
-///     type Output = SplitSlice<'a, T>;
+///     type Output = Self;
 ///
-///     fn rem(self, modulus: usize) -> Self {
+///     fn rem(self, modulus: usize) -> Self::Output {
 ///         let len = self.slice.len();
 ///         let rem = len % modulus;
 ///         let start = len - rem;
@@ -571,7 +571,7 @@ fn rem(self, other: $t) -> $t { self % other }
 /// impl Neg for Sign {
 ///     type Output = Sign;
 ///
-///     fn neg(self) -> Sign {
+///     fn neg(self) -> Self::Output {
 ///         match self {
 ///             Sign::Negative => Sign::Positive,
 ///             Sign::Zero => Sign::Zero,
@@ -650,8 +650,8 @@ macro_rules! neg_impl_unsigned {
 /// }
 ///
 /// impl AddAssign for Point {
-///     fn add_assign(&mut self, other: Point) {
-///         *self = Point {
+///     fn add_assign(&mut self, other: Self) {
+///         *self = Self {
 ///             x: self.x + other.x,
 ///             y: self.y + other.y,
 ///         };
@@ -706,8 +706,8 @@ fn add_assign(&mut self, other: $t) { *self += other }
 /// }
 ///
 /// impl SubAssign for Point {
-///     fn sub_assign(&mut self, other: Point) {
-///         *self = Point {
+///     fn sub_assign(&mut self, other: Self) {
+///         *self = Self {
 ///             x: self.x - other.x,
 ///             y: self.y - other.y,
 ///         };

src/libcore/ops/bit.rs

@@ -17,7 +17,7 @@
 /// impl Not for Answer {
 ///     type Output = Answer;
 ///
-///     fn not(self) -> Answer {
+///     fn not(self) -> Self::Output {
 ///         match self {
 ///             Answer::Yes => Answer::No,
 ///             Answer::No => Answer::Yes
@@ -75,7 +75,7 @@ fn not(self) -> $t { !self }
 ///     type Output = Self;
 ///
 ///     // rhs is the "right-hand side" of the expression `a & b`
-///     fn bitand(self, rhs: Self) -> Self {
+///     fn bitand(self, rhs: Self) -> Self::Output {
 ///         Scalar(self.0 & rhs.0)
 ///     }
 /// }
@@ -97,7 +97,7 @@ fn not(self) -> $t { !self }
 /// impl BitAnd for BooleanVector {
 ///     type Output = Self;
 ///
-///     fn bitand(self, BooleanVector(rhs): Self) -> Self {
+///     fn bitand(self, BooleanVector(rhs): Self) -> Self::Output {
 ///         let BooleanVector(lhs) = self;
 ///         assert_eq!(lhs.len(), rhs.len());
 ///         BooleanVector(lhs.iter().zip(rhs.iter()).map(|(x, y)| *x && *y).collect())
@@ -181,7 +181,7 @@ fn bitand(self, rhs: $t) -> $t { self & rhs }
 /// impl BitOr for BooleanVector {
 ///     type Output = Self;
 ///
-///     fn bitor(self, BooleanVector(rhs): Self) -> Self {
+///     fn bitor(self, BooleanVector(rhs): Self) -> Self::Output {
 ///         let BooleanVector(lhs) = self;
 ///         assert_eq!(lhs.len(), rhs.len());
 ///         BooleanVector(lhs.iter().zip(rhs.iter()).map(|(x, y)| *x || *y).collect())
@@ -243,7 +243,7 @@ fn bitor(self, rhs: $t) -> $t { self | rhs }
 ///     type Output = Self;
 ///
 ///     // rhs is the "right-hand side" of the expression `a ^ b`
-///     fn bitxor(self, rhs: Self) -> Self {
+///     fn bitxor(self, rhs: Self) -> Self::Output {
 ///         Scalar(self.0 ^ rhs.0)
 ///     }
 /// }
@@ -265,7 +265,7 @@ fn bitor(self, rhs: $t) -> $t { self | rhs }
 /// impl BitXor for BooleanVector {
 ///     type Output = Self;
 ///
-///     fn bitxor(self, BooleanVector(rhs): Self) -> Self {
+///     fn bitxor(self, BooleanVector(rhs): Self) -> Self::Output {
 ///         let BooleanVector(lhs) = self;
 ///         assert_eq!(lhs.len(), rhs.len());
 ///         BooleanVector(lhs.iter()
@@ -355,7 +355,7 @@ fn bitxor(self, other: $t) -> $t { self ^ other }
 /// impl<T: Clone> Shl<usize> for SpinVector<T> {
 ///     type Output = Self;
 ///
-///     fn shl(self, rhs: usize) -> SpinVector<T> {
+///     fn shl(self, rhs: usize) -> Self::Output {
 ///         // Rotate the vector by `rhs` places.
 ///         let (a, b) = self.vec.split_at(rhs);
 ///         let mut spun_vector: Vec<T> = vec![];
@@ -464,7 +464,7 @@ macro_rules! shl_impl_all {
 /// impl<T: Clone> Shr<usize> for SpinVector<T> {
 ///     type Output = Self;
 ///
-///     fn shr(self, rhs: usize) -> SpinVector<T> {
+///     fn shr(self, rhs: usize) -> Self::Output {
 ///         // Rotate the vector by `rhs` places.
 ///         let (a, b) = self.vec.split_at(self.vec.len() - rhs);
 ///         let mut spun_vector: Vec<T> = vec![];

src/libcore/ops/deref.rs

@@ -49,7 +49,7 @@
 /// impl<T> Deref for DerefExample<T> {
 ///     type Target = T;
 ///
-///     fn deref(&self) -> &T {
+///     fn deref(&self) -> &Self::Target {
 ///         &self.value
 ///     }
 /// }
@@ -139,13 +139,13 @@ fn deref(&self) -> &T { *self }
 /// impl<T> Deref for DerefMutExample<T> {
 ///     type Target = T;
 ///
-///     fn deref(&self) -> &T {
+///     fn deref(&self) -> &Self::Target {
 ///         &self.value
 ///     }
 /// }
 ///
 /// impl<T> DerefMut for DerefMutExample<T> {
-///     fn deref_mut(&mut self) -> &mut T {
+///     fn deref_mut(&mut self) -> &mut Self::Target {
 ///         &mut self.value
 ///     }
 /// }

src/libcore/ops/index.rs

@@ -33,7 +33,7 @@
 /// impl Index<Nucleotide> for NucleotideCount {
 ///     type Output = usize;
 ///
-///     fn index(&self, nucleotide: Nucleotide) -> &usize {
+///     fn index(&self, nucleotide: Nucleotide) -> &Self::Output {
 ///         match nucleotide {
 ///             Nucleotide::A => &self.a,
 ///             Nucleotide::C => &self.c,
@@ -105,7 +105,7 @@ pub trait Index<Idx: ?Sized> {
 /// impl Index<Side> for Balance {
 ///     type Output = Weight;
 ///
-///     fn index<'a>(&'a self, index: Side) -> &'a Weight {
+///     fn index<'a>(&'a self, index: Side) -> &'a Self::Output {
 ///         println!("Accessing {:?}-side of balance immutably", index);
 ///         match index {
 ///             Side::Left => &self.left,
@@ -115,7 +115,7 @@ pub trait Index<Idx: ?Sized> {
 /// }
 ///
 /// impl IndexMut<Side> for Balance {
-///     fn index_mut<'a>(&'a mut self, index: Side) -> &'a mut Weight {
+///     fn index_mut<'a>(&'a mut self, index: Side) -> &'a mut Self::Output {
 ///         println!("Accessing {:?}-side of balance mutably", index);
 ///         match index {
 ///             Side::Left => &mut self.left,