float, real, complex: impove docs, move docs inline, and add doctest examples

base/complex.jl

@@ -56,12 +56,25 @@ Return both the real and imaginary parts of the complex number `z`.
 """
 reim(z) = (real(z), imag(z))
 
+"""
+ real(T::Type)
+
+Returns the type that represents the real part of a value of type `T`.
+e.g: for `T == Complex{R}`, returns `R`.
+Equivalent to `typeof(real(zero(T)))`.
+
+```jldoctest
+julia> real(Complex{Int})
+Int64
+
+julia> real(Float64)
+Float64
+```
+"""
+real(T::Type) = typeof(real(zero(T)))
 real{T<:Real}(::Type{T}) = T
 real{T<:Real}(::Type{Complex{T}}) = T
 
-complex{T<:Real}(::Type{T}) = Complex{T}
-complex{T<:Real}(::Type{Complex{T}}) = Complex{T}
-
 isreal(x::Real) = true
 isreal(z::Complex) = imag(z) == 0
 """
@@ -75,9 +88,31 @@ isfinite(z::Complex) = isfinite(real(z)) & isfinite(imag(z))
 isnan(z::Complex) = isnan(real(z)) | isnan(imag(z))
 isinf(z::Complex) = isinf(real(z)) | isinf(imag(z))
 
-complex(x::Real, y::Real) = Complex(x, y)
-complex(x::Real) = Complex(x)
+"""
+ complex(r, [i])
+
+Convert real numbers or arrays to complex. `i` defaults to zero.
+"""
 complex(z::Complex) = z
+complex(x::Real) = Complex(x)
+complex(x::Real, y::Real) = Complex(x, y)
+
+"""
+ complex(T::Type)
+
+Returns an appropriate type which can represent a value of type `T` as a complex number.
+Equivalent to `typeof(complex(zero(T)))`.
+
+```jldoctest
+julia> complex(Complex{Int})
+Complex{Int64}
+
+julia> complex(Int)
+Complex{Int64}
+```
+"""
+complex{T<:Real}(::Type{T}) = Complex{T}
+complex{T<:Real}(::Type{Complex{T}}) = Complex{T}
 
 flipsign(x::Complex, y::Real) = ifelse(signbit(y), -x, x)
 

base/docs/helpdb/Base.jl

@@ -950,13 +950,6 @@ The text is assumed to be encoded in UTF-8.
 """
 eachline
 
-"""
- complex(r, [i])
-
-Convert real numbers or arrays to complex. `i` defaults to zero.
-"""
-complex
-
 """
  Mmap.Anonymous(name, readonly, create)
 
@@ -3129,14 +3122,6 @@ Unicode string.)
 """
 reverseind
 
-"""
- float(x)
-
-Convert a number, array, or string to a `AbstractFloat` data type. For numeric data, the
-smallest suitable `AbstractFloat` type is used. Converts strings to `Float64`.
-"""
-float
-
 """
  signbit(x)
 

base/float.jl

@@ -248,9 +248,28 @@ convert(::Type{AbstractFloat}, x::UInt32) = convert(Float64, x)
 convert(::Type{AbstractFloat}, x::UInt64) = convert(Float64, x) # LOSSY
 convert(::Type{AbstractFloat}, x::UInt128) = convert(Float64, x) # LOSSY
 
+"""
+ float(x)
+
+Convert a number or array to a floating point data type.
+When passed a string, this function is equivalent to `parse(Float64, x)`.
+"""
 float(x) = convert(AbstractFloat, x)
 
-# for constructing arrays
+"""
+ float(T::Type)
+
+Returns an appropriate type to represent a value of type `T` as a floating point value.
+Equivalent to `typeof(float(zero(T)))`.
+
+```jldoctest
+julia> float(Complex{Int})
+Complex{Float64}
+
+julia> float(Int)
+Float64
+```
+"""
 float{T<:Number}(::Type{T}) = typeof(float(zero(T)))
 
 for Ti in (Int8, Int16, Int32, Int64)

doc/stdlib/numbers.rst

@@ -118,7 +118,7 @@ Data Formats
 
  .. Docstring generated from Julia source
 
- Convert a number, array, or string to a ``AbstractFloat`` data type. For numeric data, the smallest suitable ``AbstractFloat`` type is used. Converts strings to ``Float64``\ .
+ Convert a number or array to a floating point data type. When passed a string, this function is equivalent to ``parse(Float64, x)``\ .
 
 .. function:: significand(x)