Auto merge of #58341 - alexreg:cosmetic-2-doc-comments, r=steveklabnik

Cosmetic improvements to doc comments

This has been factored out from rust-lang/rust#58036 to only include changes to documentation comments (throughout the rustc codebase).

r? @steveklabnik

Once you're happy with this, maybe we could get it through with r=1, so it doesn't constantly get invalidated? (I'm not sure this will be an issue, but just in case...) Anyway, thanks for your advice so far!


[git filter-repo] original commit: rust-lang/rust@b244f61

ieee.rs

@@ -186,7 +186,7 @@ impl Semantics for X87DoubleExtendedS {
     ///  exponent = all 1's, integer bit 0, significand 0 ("pseudoinfinity")
     ///  exponent = all 1's, integer bit 0, significand nonzero ("pseudoNaN")
     ///  exponent = 0, integer bit 1 ("pseudodenormal")
-    ///  exponent!=0 nor all 1's, integer bit 0 ("unnormal")
+    ///  exponent != 0 nor all 1's, integer bit 0 ("unnormal")
     /// At the moment, the first two are treated as NaNs, the second two as Normal.
     fn from_bits(bits: u128) -> IeeeFloat<Self> {
         let sign = bits & (1 << (Self::BITS - 1));
@@ -1549,11 +1549,11 @@ impl<S: Semantics> IeeeFloat<S> {
         }
     }
 
-    /// Returns TRUE if, when truncating the current number, with BIT the
+    /// Returns `true` if, when truncating the current number, with `bit` the
     /// new LSB, with the given lost fraction and rounding mode, the result
     /// would need to be rounded away from zero (i.e., by increasing the
-    /// signficand). This routine must work for Category::Zero of both signs, and
-    /// Category::Normal numbers.
+    /// signficand). This routine must work for `Category::Zero` of both signs, and
+    /// `Category::Normal` numbers.
     fn round_away_from_zero(&self, round: Round, loss: Loss, bit: usize) -> bool {
         // NaNs and infinities should not have lost fractions.
         assert!(self.is_finite_non_zero() || self.is_zero());
@@ -2257,7 +2257,7 @@ impl Loss {
         more_significant
     }
 
-    /// Return the fraction lost were a bignum truncated losing the least
+    /// Returns the fraction lost were a bignum truncated losing the least
     /// significant `bits` bits.
     fn through_truncation(limbs: &[Limb], bits: usize) -> Loss {
         if bits == 0 {
@@ -2320,12 +2320,12 @@ mod sig {
         Ordering::Equal
     }
 
-    /// Extract the given bit.
+    /// Extracts the given bit.
     pub(super) fn get_bit(limbs: &[Limb], bit: usize) -> bool {
         limbs[bit / LIMB_BITS] & (1 << (bit % LIMB_BITS)) != 0
     }
 
-    /// Set the given bit.
+    /// Sets the given bit.
     pub(super) fn set_bit(limbs: &mut [Limb], bit: usize) {
         limbs[bit / LIMB_BITS] |= 1 << (bit % LIMB_BITS);
     }
@@ -2335,7 +2335,7 @@ mod sig {
         limbs[bit / LIMB_BITS] &= !(1 << (bit % LIMB_BITS));
     }
 
-    /// Shift `dst` left `bits` bits, subtract `bits` from its exponent.
+    /// Shifts `dst` left `bits` bits, subtract `bits` from its exponent.
     pub(super) fn shift_left(dst: &mut [Limb], exp: &mut ExpInt, bits: usize) {
         if bits > 0 {
             // Our exponent should not underflow.
@@ -2367,7 +2367,7 @@ mod sig {
         }
     }
 
-    /// Shift `dst` right `bits` bits noting lost fraction.
+    /// Shifts `dst` right `bits` bits noting lost fraction.
     pub(super) fn shift_right(dst: &mut [Limb], exp: &mut ExpInt, bits: usize) -> Loss {
         let loss = Loss::through_truncation(dst, bits);
 
@@ -2403,7 +2403,7 @@ mod sig {
         loss
     }
 
-    /// Copy the bit vector of width `src_bits` from `src`, starting at bit SRC_LSB,
+    /// Copies the bit vector of width `src_bits` from `src`, starting at bit SRC_LSB,
     /// to `dst`, such that the bit SRC_LSB becomes the least significant bit of `dst`.
     /// All high bits above `src_bits` in `dst` are zero-filled.
     pub(super) fn extract(dst: &mut [Limb], src: &[Limb], src_bits: usize, src_lsb: usize) {

lib.rs

@@ -375,7 +375,7 @@ pub trait Float
     fn from_str_r(s: &str, round: Round) -> Result<StatusAnd<Self>, ParseError>;
     fn to_bits(self) -> u128;
 
-    /// Convert a floating point number to an integer according to the
+    /// Converts a floating point number to an integer according to the
     /// rounding mode. In case of an invalid operation exception,
     /// deterministic values are returned, namely zero for NaNs and the
     /// minimal or maximal value respectively for underflow or overflow.
@@ -388,7 +388,7 @@ pub trait Float
     ///
     /// The *is_exact output tells whether the result is exact, in the sense
     /// that converting it back to the original floating point type produces
-    /// the original value. This is almost equivalent to result==Status::OK,
+    /// the original value. This is almost equivalent to `result == Status::OK`,
     /// except for negative zeroes.
     fn to_i128_r(self, width: usize, round: Round, is_exact: &mut bool) -> StatusAnd<i128> {
         let status;
@@ -458,48 +458,48 @@ pub trait Float
         }
     }
 
-    /// IEEE-754R isSignMinus: Returns true if and only if the current value is
+    /// IEEE-754R isSignMinus: Returns whether the current value is
     /// negative.
     ///
     /// This applies to zeros and NaNs as well.
     fn is_negative(self) -> bool;
 
-    /// IEEE-754R isNormal: Returns true if and only if the current value is normal.
+    /// IEEE-754R isNormal: Returns whether the current value is normal.
     ///
     /// This implies that the current value of the float is not zero, subnormal,
     /// infinite, or NaN following the definition of normality from IEEE-754R.
     fn is_normal(self) -> bool {
         !self.is_denormal() && self.is_finite_non_zero()
     }
 
-    /// Returns true if and only if the current value is zero, subnormal, or
+    /// Returns `true` if the current value is zero, subnormal, or
     /// normal.
     ///
     /// This means that the value is not infinite or NaN.
     fn is_finite(self) -> bool {
         !self.is_nan() && !self.is_infinite()
     }
 
-    /// Returns true if and only if the float is plus or minus zero.
+    /// Returns `true` if the float is plus or minus zero.
     fn is_zero(self) -> bool {
         self.category() == Category::Zero
     }
 
-    /// IEEE-754R isSubnormal(): Returns true if and only if the float is a
+    /// IEEE-754R isSubnormal(): Returns whether the float is a
     /// denormal.
     fn is_denormal(self) -> bool;
 
-    /// IEEE-754R isInfinite(): Returns true if and only if the float is infinity.
+    /// IEEE-754R isInfinite(): Returns whether the float is infinity.
     fn is_infinite(self) -> bool {
         self.category() == Category::Infinity
     }
 
-    /// Returns true if and only if the float is a quiet or signaling NaN.
+    /// Returns `true` if the float is a quiet or signaling NaN.
     fn is_nan(self) -> bool {
         self.category() == Category::NaN
     }
 
-    /// Returns true if and only if the float is a signaling NaN.
+    /// Returns `true` if the float is a signaling NaN.
     fn is_signaling(self) -> bool;
 
     // Simple Queries
@@ -518,19 +518,19 @@ pub trait Float
         self.is_zero() && self.is_negative()
     }
 
-    /// Returns true if and only if the number has the smallest possible non-zero
+    /// Returns `true` if the number has the smallest possible non-zero
     /// magnitude in the current semantics.
     fn is_smallest(self) -> bool {
         Self::SMALLEST.copy_sign(self).bitwise_eq(self)
     }
 
-    /// Returns true if and only if the number has the largest possible finite
+    /// Returns `true` if the number has the largest possible finite
     /// magnitude in the current semantics.
     fn is_largest(self) -> bool {
         Self::largest().copy_sign(self).bitwise_eq(self)
     }
 
-    /// Returns true if and only if the number is an exact integer.
+    /// Returns `true` if the number is an exact integer.
     fn is_integer(self) -> bool {
         // This could be made more efficient; I'm going for obviously correct.
         if !self.is_finite() {
@@ -572,11 +572,11 @@ pub trait Float
 }
 
 pub trait FloatConvert<T: Float>: Float {
-    /// Convert a value of one floating point type to another.
+    /// Converts a value of one floating point type to another.
     /// The return value corresponds to the IEEE754 exceptions. *loses_info
     /// records whether the transformation lost information, i.e., whether
     /// converting the result back to the original type will produce the
-    /// original value (this is almost the same as return value==Status::OK,
+    /// original value (this is almost the same as return `value == Status::OK`,
     /// but there are edge cases where this is not so).
     fn convert_r(self, round: Round, loses_info: &mut bool) -> StatusAnd<T>;
     fn convert(self, loses_info: &mut bool) -> StatusAnd<T> {