Add accuracy note for 2-arg log (#18360)

* Add accuracy note for 2-arg log

Addresses #18298.

* update based on comments

(cherry picked from commit 5f74d16)

Author: simonbyrne

base/docs/helpdb/Base.jl

@@ -2571,13 +2571,6 @@ faster and more accurate.
 """
 log(x)
 
-"""
-    log(b,x)
-
-Compute the base `b` logarithm of `x`. Throws `DomainError` for negative `Real` arguments.
-"""
-log(b, x)
-
 """
     trunc([T,] x, [digits, [base]])
 

base/math.jl

@@ -120,6 +120,32 @@ deg2rad(z::Real) = deg2rad(float(z))
 @vectorize_1arg Real deg2rad
 
 log{T<:Number}(b::T, x::T) = log(x)/log(b)
+
+"""
+    log(b,x)
+
+Compute the base `b` logarithm of `x`. Throws `DomainError` for negative `Real` arguments.
+
+```jldoctest
+julia> log(4,8)
+1.5
+
+julia> log(4,2)
+0.5
+```
+
+!!! note
+    If `b` is a power of 2 or 10, `log2` or `log10` should be used, as these will
+    typically be faster and more accurate. For example,
+
+    ```jldoctest
+    julia> log(100,1000000)
+    2.9999999999999996
+
+    julia> log10(1000000)/2
+    3.0
+    ```
+"""
 log(b::Number, x::Number) = log(promote(b,x)...)
 @vectorize_2arg Number log
 

doc/stdlib/math.rst

@@ -794,6 +794,26 @@ Mathematical Functions
 
    Compute the base ``b`` logarithm of ``x``\ . Throws ``DomainError`` for negative ``Real`` arguments.
 
+   .. doctest::
+
+       julia> log(4,8)
+       1.5
+
+       julia> log(4,2)
+       0.5
+
+   .. note::
+      If ``b`` is a power of 2 or 10, ``log2`` or ``log10`` should be used, as these will typically be faster and more accurate. For example,
+
+      .. doctest::
+
+          julia> log(100,1000000)
+          2.9999999999999996
+
+          julia> log10(1000000)/2
+          3.0
+
+
 .. function:: log2(x)
 
    .. Docstring generated from Julia source