Rollup merge of rust-lang#47277 - tspiteri:log-correctness, r=frewsxcv

doc: show that `f32::log` and `f64::log` are not correctly rounded

Fixes rust-lang#47273.

One thing I'm not sure about is whether the "calculated as `self.ln() / base.ln()`" bit is being too specific, maybe we do not want to make this such a strong commitment. I think it's fine, but we should not make commitments in the API documentation by accident.

In case that is removed, the added sentence "`self.log2()` can ... base 10." still makes it amply clear that the `log` methods can be more inaccurate than other methods. If the above clause is removed, this second sentence can be moved to the first paragraph, kind of like the accuracy comment for the [`mul_add`](https://doc.rust-lang.org/std/primitive.f32.html#method.mul_add) method.

Author: GuillaumeGomez

src/libstd/f32.rs

@@ -472,20 +472,19 @@ impl f32 {
 
     /// Returns the logarithm of the number with respect to an arbitrary base.
     ///
+    /// The result may not be correctly rounded owing to implementation details;
+    /// `self.log2()` can produce more accurate results for base 2, and
+    /// `self.log10()` can produce more accurate results for base 10.
+    ///
     /// ```
     /// use std::f32;
     ///
-    /// let ten = 10.0f32;
-    /// let two = 2.0f32;
-    ///
-    /// // log10(10) - 1 == 0
-    /// let abs_difference_10 = (ten.log(10.0) - 1.0).abs();
+    /// let five = 5.0f32;
     ///
-    /// // log2(2) - 1 == 0
-    /// let abs_difference_2 = (two.log(2.0) - 1.0).abs();
+    /// // log5(5) - 1 == 0
+    /// let abs_difference = (five.log(5.0) - 1.0).abs();
     ///
-    /// assert!(abs_difference_10 <= f32::EPSILON);
-    /// assert!(abs_difference_2 <= f32::EPSILON);
+    /// assert!(abs_difference <= f32::EPSILON);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]

src/libstd/f64.rs

@@ -432,18 +432,17 @@ impl f64 {
 
     /// Returns the logarithm of the number with respect to an arbitrary base.
     ///
-    /// ```
-    /// let ten = 10.0_f64;
-    /// let two = 2.0_f64;
+    /// The result may not be correctly rounded owing to implementation details;
+    /// `self.log2()` can produce more accurate results for base 2, and
+    /// `self.log10()` can produce more accurate results for base 10.
     ///
-    /// // log10(10) - 1 == 0
-    /// let abs_difference_10 = (ten.log(10.0) - 1.0).abs();
+    /// ```
+    /// let five = 5.0_f64;
     ///
-    /// // log2(2) - 1 == 0
-    /// let abs_difference_2 = (two.log(2.0) - 1.0).abs();
+    /// // log5(5) - 1 == 0
+    /// let abs_difference = (five.log(5.0) - 1.0).abs();
     ///
-    /// assert!(abs_difference_10 < 1e-10);
-    /// assert!(abs_difference_2 < 1e-10);
+    /// assert!(abs_difference < 1e-10);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]