Expand docs for eps (JuliaLang#20597)

* Expand docs for eps

Fixed JuliaLang#20542 and JuliaLang#13447.

* add doctests

* clarify rationale, US spelling, use where

Author: simonbyrne

base/docs/helpdb/Base.jl

@@ -1127,28 +1127,6 @@ Delete the mapping for the given key in a collection, and return the collection.
 """
 delete!
 
-"""
-    eps(T)
-
-The distance between 1.0 and the next larger representable floating-point value of
-`DataType` `T`. Only floating-point types are sensible arguments.
-"""
-eps(::Union{Type{BigFloat},Type{Float64},Type{Float32},Type{Float16}})
-
-"""
-    eps()
-
-The distance between 1.0 and the next larger representable floating-point value of `Float64`.
-"""
-eps()
-
-"""
-    eps(x)
-
-The distance between `x` and the next larger representable floating-point value of the same
-`DataType` as `x`.
-"""
-eps(::AbstractFloat)
 
 """
     searchsortedfirst(a, x, [by=<transform>,] [lt=<comparison>,] [rev=false])

base/float.jl

@@ -711,6 +711,74 @@ end
     eps() = eps(Float64)
 end
 
+"""
+    eps(::Type{T}) where T<:AbstractFloat
+    eps()
+
+Returns the *machine epsilon* of the floating point type `T` (`T = Float64` by
+default). This is defined as the gap between 1 and the next largest value representable by
+`T`, and is equivalent to `eps(one(T))`.
+
+```jldoctest
+julia> eps()
+2.220446049250313e-16
+
+julia> eps(Float32)
+1.1920929f-7
+
+julia> 1.0 + eps()
+1.0000000000000002
+
+julia> 1.0 + eps()/2
+1.0
+```
+"""
+eps(::Type{<:AbstractFloat})
+
+"""
+    eps(x::AbstractFloat)
+
+Returns the *unit in last place* (ulp) of `x`. This is the distance between consecutive
+representable floating point values at `x`. In most cases, if the distance on either side
+of `x` is different, then the larger of the two is taken, that is
+
+    eps(x) == max(x-prevfloat(x), nextfloat(x)-x)
+
+The exceptions to this rule are the smallest and largest finite values
+(e.g. `nextfloat(-Inf)` and `prevfloat(Inf)` for `Float64`), which round to the smaller of
+the values.
+
+The rationale for this behavior is that `eps` bounds the floating point rounding
+error. Under the default `RoundNearest` rounding mode, if ``y`` is a real number and ``x``
+is the nearest floating point number to ``y``, then
+
+```math
+|y-x| \\leq \\operatorname{eps}(x)/2.
+```
+
+```jldoctest
+julia> eps(1.0)
+2.220446049250313e-16
+
+julia> eps(prevfloat(2.0))
+2.220446049250313e-16
+
+julia> eps(2.0)
+4.440892098500626e-16
+
+julia> x = prevfloat(Inf)      # largest finite Float64
+1.7976931348623157e308
+
+julia> x + eps(x)/2            # rounds up
+Inf
+
+julia> x + prevfloat(eps(x)/2) # rounds down
+1.7976931348623157e308
+```
+"""
+eps(::AbstractFloat)
+
+
 ## byte order swaps for arbitrary-endianness serialization/deserialization ##
 bswap(x::Float32) = bswap_int(x)
 bswap(x::Float64) = bswap_int(x)

doc/src/stdlib/base.md

@@ -97,8 +97,7 @@ Base.realmin
 Base.realmax
 Base.maxintfloat
 Base.sizeof(::Type)
-Base.eps(::Union{Type{BigFloat},Type{Float64},Type{Float32},Type{Float16}})
-Base.eps()
+Base.eps(::Type{<:AbstractFloat})
 Base.eps(::AbstractFloat)
 Base.promote_type
 Base.promote_rule