deprecate atan2, and update docs

base/deprecated.jl

@@ -1680,6 +1680,9 @@ end
 
 @eval @deprecate $(Symbol("@schedule")) $(Symbol("@async"))
 
+@deprecate atan2(y, x) atan(y, x)
+
+
 # END 0.7 deprecations
 
 # BEGIN 1.0 deprecations

base/exports.jl

@@ -212,7 +212,6 @@ export
     asind,
     asinh,
     atan,
-    atan2,
     atand,
     atanh,
     big,

base/fastmath.jl

@@ -57,7 +57,6 @@ const fast_op =
          :asin => :asin_fast,
          :asinh => :asinh_fast,
          :atan => :atan_fast,
-         :atan2 => :atan2_fast,
          :atanh => :atanh_fast,
          :cbrt => :cbrt_fast,
          :cis => :cis_fast,
@@ -293,9 +292,9 @@ pow_fast(x::Float32, y::Float32) =
 pow_fast(x::Float64, y::Float64) =
     ccall(("pow",libm), Float64, (Float64,Float64), x, y)
 
-atan2_fast(x::Float32, y::Float32) =
+atan_fast(x::Float32, y::Float32) =
     ccall(("atan2f",libm), Float32, (Float32,Float32), x, y)
-atan2_fast(x::Float64, y::Float64) =
+atan_fast(x::Float64, y::Float64) =
     ccall(("atan2",libm), Float64, (Float64,Float64), x, y)
 
 asin_fast(x::FloatTypes) = asin(x)
@@ -349,7 +348,7 @@ sincos_fast(v) = (sin_fast(v), cos_fast(v))
     acos_fast(x::T) where {T<:ComplexTypes} =
         convert(T,π)/2 + im*log(im*x + sqrt(1-x*x))
     acosh_fast(x::ComplexTypes) = log(x + sqrt(x+1) * sqrt(x-1))
-    angle_fast(x::ComplexTypes) = atan2(imag(x), real(x))
+    angle_fast(x::ComplexTypes) = atan(imag(x), real(x))
     asin_fast(x::ComplexTypes) = -im*asinh(im*x)
     asinh_fast(x::ComplexTypes) = log(x + sqrt(1+x*x))
     atan_fast(x::ComplexTypes) = -im*atanh(im*x)
@@ -387,7 +386,7 @@ for f in (:acos, :acosh, :angle, :asin, :asinh, :atan, :atanh, :cbrt,
     end
 end
 
-for f in (:^, :atan2, :hypot, :max, :min, :minmax, :log)
+for f in (:^, :atan, :hypot, :max, :min, :minmax, :log)
     f_fast = fast_op[f]
     @eval begin
         # fall-back implementation for non-numeric types

base/math.jl

@@ -7,7 +7,7 @@ export sin, cos, sincos, tan, sinh, cosh, tanh, asin, acos, atan,
        sech, csch, coth, asech, acsch, acoth,
        sinpi, cospi, sinc, cosc,
        cosd, cotd, cscd, secd, sind, tand,
-       acosd, acotd, acscd, asecd, asind, atand, atan2,
+       acosd, acotd, acscd, asecd, asind, atand,
        rad2deg, deg2rad,
        log, log2, log10, log1p, exponent, exp, exp2, exp10, expm1,
        cbrt, sqrt, significand,
@@ -234,10 +234,20 @@ tanh(x::Number)
     atan(y)
     atan(y, x)
 
-Compute the inverse tangent of `y`, where the output is in radians.
+Compute the inverse tangent of `y` or `y/x`, respectively.
+
+which gives the angle in [radians](https://en.wikipedia.org/wiki/Radian) between the *x*-axis
+and the point specified by its arguments, interpreted as *x* and *y* coordinates.
+
+
+For one argument, this is the angle in radians between the positive *x*-axis and the point
+(1, *y*), returning a value in the interval ``[-\pi/2, \pi/2]``.
+
+For two arguments, this is the angle in radians between the positive *x*-axis and the
+point (*x*, *y*), returning a value in the interval ``[-pi, pi]``. This corresponds to a
+typical [`atan2`](https://en.wikipedia.org/wiki/Atan2) function.
 """
 atan(x::Number)
-atan(x::Number)
 
 """
     asinh(x)
@@ -507,23 +517,6 @@ Compute the hypotenuse ``\\sqrt{\\sum x_i^2}`` avoiding overflow and underflow.
 """
 hypot(x::Number...) = sqrt(sum(abs2(y) for y in x))
 
-"""
-    atan2(y, x)
-
-Compute the inverse tangent of `y/x`, using the signs of both `x` and `y` to determine the
-quadrant of the return value.
-
-This is also available via [`atan`](@ref), but `atan2` is provided for compatibility
-purposes.
-"""
-atan2(y, x) = atan(y, x)
-
-"""
-    atan(y, x)
-
-Compute the inverse tangent of `y/x`, using the signs of both `x` and `y` to determine the
-quadrant of the return value.
-"""
 atan(y::Real, x::Real) = atan(promote(float(y),float(x))...)
 atan(y::T, x::T) where {T<:AbstractFloat} = Base.no_op_err("atan", T)
 

doc/src/base/math.md

@@ -72,7 +72,6 @@ Base.tanh(::Number)
 Base.asin(::Number)
 Base.acos(::Number)
 Base.atan(::Number)
-Base.Math.atan2
 Base.Math.asind
 Base.Math.acosd
 Base.Math.atand

doc/src/manual/mathematical-operations.md

@@ -528,12 +528,11 @@ sin    cos    tan    cot    sec    csc
 sinh   cosh   tanh   coth   sech   csch
 asin   acos   atan   acot   asec   acsc
 asinh  acosh  atanh  acoth  asech  acsch
-sinc   cosc   atan2
+sinc   cosc
 ```
 
-These are all single-argument functions, with the exception of [atan2](https://en.wikipedia.org/wiki/Atan2),
-which gives the angle in [radians](https://en.wikipedia.org/wiki/Radian) between the *x*-axis
-and the point specified by its arguments, interpreted as *x* and *y* coordinates.
+These are all single-argument functions, with [`atan`](@ref) also accepting two arguments
+corresponding to a traditional [`atan2`](https://en.wikipedia.org/wiki/Atan2) function.
 
 Additionally, [`sinpi(x)`](@ref) and [`cospi(x)`](@ref) are provided for more accurate computations
 of [`sin(pi*x)`](@ref) and [`cos(pi*x)`](@ref) respectively.