Rollup merge of rust-lang#88713 - falk-hueffner:int-log10-documentati…

…on-fixes, r=scottmcm Improve docs for int_log * Clarify rounding. * Avoid "wrapping" wording. * Omit wrong claim on 0 only being returned in error cases. * Typo fix for one_less_than_next_power_of_two.
matthiaskrgr · Oct 10, 2021 · e5ea3f2 · e5ea3f2
2 parents c1cb974 + 138ebd1
commit e5ea3f2
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 25 deletions.
diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs
@@ -2199,7 +2199,8 @@ macro_rules! int_impl {
             }
         }
 
-        /// Returns the logarithm of the number with respect to an arbitrary base.
+        /// Returns the logarithm of the number with respect to an arbitrary base,
+        /// rounded down.
         ///
         /// This method might not be optimized owing to implementation details;
         /// `log2` can produce results more efficiently for base 2, and `log10`
@@ -2208,8 +2209,8 @@ macro_rules! int_impl {
         /// # Panics
         ///
         /// When the number is zero, or if the base is not at least 2; it
-        /// panics in debug mode and the return value is wrapped to 0 in release
-        /// mode (the only situation in which the method can return 0).
+        /// panics in debug mode and the return value is 0 in release
+        /// mode.
         ///
         /// # Examples
         ///
@@ -2237,13 +2238,12 @@ macro_rules! int_impl {
             }
         }
 
-        /// Returns the base 2 logarithm of the number.
+        /// Returns the base 2 logarithm of the number, rounded down.
         ///
         /// # Panics
         ///
         /// When the number is zero it panics in debug mode and the return value
-        /// is wrapped to 0 in release mode (the only situation in which the
-        /// method can return 0).
+        /// is 0 in release mode.
         ///
         /// # Examples
         ///
@@ -2271,13 +2271,12 @@ macro_rules! int_impl {
             }
         }
 
-        /// Returns the base 10 logarithm of the number.
+        /// Returns the base 10 logarithm of the number, rounded down.
         ///
         /// # Panics
         ///
         /// When the number is zero it panics in debug mode and the return value
-        /// is wrapped to 0 in release mode (the only situation in which the
-        /// method can return 0).
+        /// is 0 in release mode.
         ///
         /// # Example
         ///
@@ -2305,7 +2304,8 @@ macro_rules! int_impl {
             }
         }
 
-        /// Returns the logarithm of the number with respect to an arbitrary base.
+        /// Returns the logarithm of the number with respect to an arbitrary base,
+        /// rounded down.
         ///
         /// Returns `None` if the number is negative or zero, or if the base is not at least 2.
         ///
@@ -2345,7 +2345,7 @@ macro_rules! int_impl {
             }
         }
 
-        /// Returns the base 2 logarithm of the number.
+        /// Returns the base 2 logarithm of the number, rounded down.
         ///
         /// Returns `None` if the number is negative or zero.
         ///
@@ -2369,7 +2369,7 @@ macro_rules! int_impl {
             }
         }
 
-        /// Returns the base 10 logarithm of the number.
+        /// Returns the base 10 logarithm of the number, rounded down.
         ///
         /// Returns `None` if the number is negative or zero.
         ///

diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs
@@ -658,7 +658,8 @@ macro_rules! uint_impl {
             }
         }
 
-        /// Returns the logarithm of the number with respect to an arbitrary base.
+        /// Returns the logarithm of the number with respect to an arbitrary base,
+        /// rounded down.
         ///
         /// This method might not be optimized owing to implementation details;
         /// `log2` can produce results more efficiently for base 2, and `log10`
@@ -667,8 +668,7 @@ macro_rules! uint_impl {
         /// # Panics
         ///
         /// When the number is negative, zero, or if the base is not at least 2;
-        /// it panics in debug mode and the return value is wrapped to 0 in
-        /// release mode (the only situation in which the method can return 0).
+        /// it panics in debug mode and the return value is 0 in release mode.
         ///
         /// # Examples
         ///
@@ -696,13 +696,12 @@ macro_rules! uint_impl {
             }
         }
 
-        /// Returns the base 2 logarithm of the number.
+        /// Returns the base 2 logarithm of the number, rounded down.
         ///
         /// # Panics
         ///
         /// When the number is negative or zero it panics in debug mode and
-        /// the return value is wrapped to 0 in release mode (the only situation in
-        /// which the method can return 0).
+        /// the return value is 0 in release mode.
         ///
         /// # Examples
         ///
@@ -730,13 +729,12 @@ macro_rules! uint_impl {
             }
         }
 
-        /// Returns the base 10 logarithm of the number.
+        /// Returns the base 10 logarithm of the number, rounded down.
         ///
         /// # Panics
         ///
         /// When the number is negative or zero it panics in debug mode and the
-        /// return value is wrapped to 0 in release mode (the only situation in
-        /// which the method can return 0).
+        /// return value is 0 in release mode.
         ///
         /// # Example
         ///
@@ -764,7 +762,8 @@ macro_rules! uint_impl {
             }
         }
 
-        /// Returns the logarithm of the number with respect to an arbitrary base.
+        /// Returns the logarithm of the number with respect to an arbitrary base,
+        /// rounded down.
         ///
         /// Returns `None` if the number is zero, or if the base is not at least 2.
         ///
@@ -804,7 +803,7 @@ macro_rules! uint_impl {
             }
         }
 
-        /// Returns the base 2 logarithm of the number.
+        /// Returns the base 2 logarithm of the number, rounded down.
         ///
         /// Returns `None` if the number is zero.
         ///
@@ -828,7 +827,7 @@ macro_rules! uint_impl {
             }
         }
 
-        /// Returns the base 10 logarithm of the number.
+        /// Returns the base 10 logarithm of the number, rounded down.
         ///
         /// Returns `None` if the number is zero.
         ///
@@ -2120,7 +2119,7 @@ macro_rules! uint_impl {
         /// Returns the smallest power of two greater than or equal to `self`.
         ///
         /// When return value overflows (i.e., `self > (1 << (N-1))` for type
-        /// `uN`), it panics in debug mode and return value is wrapped to 0 in
+        /// `uN`), it panics in debug mode and the return value is wrapped to 0 in
         /// release mode (the only situation in which method can return 0).
         ///
         /// # Examples