Merge pull request #17417 from MichaelHatherly/mh/missing-const-docs

Move RST 'data' docstrings inline

base/c.jl

@@ -6,15 +6,69 @@ import Core.Intrinsics: cglobal, box
 
 cfunction(f::Function, r, a) = ccall(:jl_function_ptr, Ptr{Void}, (Any, Any, Any), f, r, a)
 
+"""
+    Ptr{T}
+
+A memory address referring to data of type `T`.  However, there is no guarantee that the
+memory is actually valid, or that it actually represents data of the specified type.
+"""
+Ptr
+
+"""
+    Ref{T}
+
+An object that safely references data of type `T`. This type is guaranteed to point to
+valid, Julia-allocated memory of the correct type. The underlying data is protected from
+freeing by the garbage collector as long as the `Ref` itself is referenced.
+
+When passed as a `ccall` argument (either as a `Ptr` or `Ref` type), a `Ref` object will be
+converted to a native pointer to the data it references.
+
+There is no invalid (NULL) `Ref`.
+"""
+Ref
+
 if ccall(:jl_is_char_signed, Ref{Bool}, ())
     typealias Cchar Int8
 else
     typealias Cchar UInt8
 end
+"""
+    Cchar
+
+Equivalent to the native `char` c-type.
+"""
+Cchar
+
+"""
+    Cuchar
+
+Equivalent to the native `unsigned char` c-type (`UInt8`).
+"""
 typealias Cuchar UInt8
+"""
+    Cshort
+
+Equivalent to the native `signed short` c-type (`Int16`).
+"""
 typealias Cshort Int16
+"""
+    Cushort
+
+Equivalent to the native `unsigned short` c-type (`UInt16`).
+"""
 typealias Cushort UInt16
+"""
+    Cint
+
+Equivalent to the native `signed int` c-type (`Int32`).
+"""
 typealias Cint Int32
+"""
+    Cuint
+
+Equivalent to the native `unsigned int` c-type (`UInt32`).
+"""
 typealias Cuint UInt32
 if is_windows()
     typealias Clong Int32
@@ -25,14 +79,78 @@ else
     typealias Culong UInt
     typealias Cwchar_t Int32
 end
+"""
+    Clong
+
+Equivalent to the native `signed long` c-type.
+"""
+Clong
+"""
+    Culong
+
+Equivalent to the native `unsigned long` c-type.
+"""
+Culong
+"""
+    Cwchar_t
+
+Equivalent to the native `wchar_t` c-type (`Int32`).
+"""
+Cwchar_t
+
+"""
+    Cptrdiff_t
+
+Equivalent to the native `ptrdiff_t` c-type (`Int`).
+"""
 typealias Cptrdiff_t Int
+"""
+    Csize_t
+
+Equivalent to the native `size_t` c-type (`UInt`).
+"""
 typealias Csize_t UInt
+"""
+    Cssize_t
+
+Equivalent to the native `ssize_t` c-type.
+"""
 typealias Cssize_t Int
+"""
+    Cintmax_t
+
+Equivalent to the native `intmax_t` c-type (`Int64`).
+"""
 typealias Cintmax_t Int64
+"""
+    Cuintmax_t
+
+Equivalent to the native `uintmax_t` c-type (`UInt64`).
+"""
 typealias Cuintmax_t UInt64
+"""
+    Clonglong
+
+Equivalent to the native `signed long long` c-type (`Int64`).
+"""
 typealias Clonglong Int64
+"""
+    Culonglong
+
+Equivalent to the native `unsigned long long` c-type (`UInt64`).
+"""
 typealias Culonglong UInt64
+"""
+    Cfloat
+
+Equivalent to the native `float` c-type (`Float32`).
+"""
 typealias Cfloat Float32
+"""
+    Cdouble
+
+Equivalent to the native `double` c-type (`Float64`).
+"""
 typealias Cdouble Float64
 
 if !is_windows()

base/complex.jl

@@ -7,6 +7,11 @@ end
 Complex(x::Real, y::Real) = Complex(promote(x,y)...)
 Complex(x::Real) = Complex(x, zero(x))
 
+"""
+    im
+
+The imaginary unit.
+"""
 const im = Complex(false,true)
 
 typealias Complex128 Complex{Float64}

base/dates/types.jl

@@ -2,6 +2,19 @@
 
 abstract AbstractTime
 
+"""
+    Period
+    Year
+    Month
+    Week
+    Day
+    Hour
+    Minute
+    Second
+    Millisecond
+
+`Period` types represent discrete, human representations of time.
+"""
 abstract Period     <: AbstractTime
 abstract DatePeriod <: Period
 abstract TimePeriod <: Period
@@ -19,10 +32,36 @@ for T in (:Hour,:Minute,:Second,:Millisecond)
     end
 end
 
-# Instant types represent different monotonically increasing timelines
+"""
+    Year(v)
+    Month(v)
+    Week(v)
+    Day(v)
+    Hour(v)
+    Minute(v)
+    Second(v)
+    Millisecond(v)
+
+Construct a `Period` type with the given `v` value. Input must be losslessly convertible
+to an `Int64`.
+"""
+Period(v)
+
+"""
+    Instant
+
+`Instant` types represent integer-based, machine representations of time as continuous
+timelines starting from an epoch.
+"""
 abstract Instant <: AbstractTime
 
-# UTInstant is based on UT seconds, or 1/86400th of a turn of the earth
+"""
+    UTInstant{T}
+
+The `UTInstant` represents a machine timeline based on UT time (1 day = one revolution of
+the earth). The `T` is a `Period` parameter that indicates the resolution or precision of
+the instant.
+"""
 immutable UTInstant{P<:Period} <: Instant
     periods::P
 end
@@ -43,16 +82,30 @@ immutable ISOCalendar <: Calendar end
 abstract TimeZone
 immutable UTC <: TimeZone end
 
-# TimeTypes wrap Instants to provide human representations of time
+"""
+    TimeType
+
+`TimeType` types wrap `Instant` machine instances to provide human representations of the
+machine instant. Both `DateTime` and `Date` are subtypes of `TimeType`.
+"""
 abstract TimeType <: AbstractTime
 
-# DateTime is a millisecond precision UTInstant interpreted by ISOCalendar
+"""
+    DateTime
+
+`DateTime` wraps a `UTInstant{Millisecond}` and interprets it according to the proleptic
+Gregorian calendar.
+"""
 immutable DateTime <: TimeType
     instant::UTInstant{Millisecond}
     DateTime(instant::UTInstant{Millisecond}) = new(instant)
 end
 
-# DateTime is a day precision UTInstant interpreted by ISOCalendar
+"""
+    Date
+
+`Date` wraps a `UTInstant{Day}` and interprets it according to the proleptic Gregorian calendar.
+"""
 immutable Date <: TimeType
     instant::UTInstant{Day}
     Date(instant::UTInstant{Day}) = new(instant)

base/docs/basedocs.jl

@@ -657,6 +657,13 @@ kw"immutable"
 """
 kw"@__LINE__"
 
+"""
+    ans
+
+A variable referring to the last computed value, automatically set at the interactive prompt.
+"""
+kw"ans"
+
 """
     nothing
 
@@ -673,4 +680,16 @@ generation specialization for that field.
 """
 ANY
 
+"""
+    DevNull
+
+Used in a stream redirect to discard all data written to it. Essentially equivalent to
+/dev/null on Unix or NUL on Windows. Usage:
+
+```julia
+run(pipeline(`cat test.txt`, DevNull))
+```
+"""
+DevNull
+
 end

base/float.jl

@@ -2,13 +2,44 @@
 
 ## floating point traits ##
 
+"""
+    Inf16
+
+Positive infinity of type `Float16`.
+"""
 const Inf16 = box(Float16,unbox(UInt16,0x7c00))
+"""
+    NaN16
+
+A not-a-number value of type `Float16`.
+"""
 const NaN16 = box(Float16,unbox(UInt16,0x7e00))
+"""
+    Inf32
+
+Positive infinity of type `Float32`.
+"""
 const Inf32 = box(Float32,unbox(UInt32,0x7f800000))
+"""
+    NaN32
+
+A not-a-number value of type `Float32`.
+"""
 const NaN32 = box(Float32,unbox(UInt32,0x7fc00000))
 const Inf64 = box(Float64,unbox(UInt64,0x7ff0000000000000))
 const NaN64 = box(Float64,unbox(UInt64,0x7ff8000000000000))
+
+"""
+    Inf
+
+Positive infinity of type `Float64`.
+"""
 const Inf = Inf64
+"""
+    NaN
+
+A not-a-number value of type `Float64`.
+"""
 const NaN = NaN64
 
 ## conversions to floating-point ##

base/irrationals.jl

@@ -131,11 +131,45 @@ big(x::Irrational) = convert(BigFloat,x)
 @irrational φ        1.61803398874989484820  (1+sqrt(big(5)))/2
 
 # aliases
+"""
+    pi
+    π
+
+The constant pi.
+"""
 const pi = π
+
+"""
+    e
+    eu
+
+The constant e.
+"""
 const eu = e
+
+"""
+    γ
+    eulergamma
+
+Euler's constant.
+"""
 const eulergamma = γ
+
+"""
+    φ
+    golden
+
+The golden ratio.
+"""
 const golden = φ
 
+"""
+    catalan
+
+Catalan's constant.
+"""
+catalan
+
 # special behaviors
 
 # use exp for e^x or e.^x, as in

base/linalg/uniformscaling.jl

@@ -7,6 +7,11 @@ immutable UniformScaling{T<:Number}
     λ::T
 end
 
+"""
+    I
+
+An object of type `UniformScaling`, representing an identity matrix of any size.
+"""
 const I = UniformScaling(1)
 
 eltype{T}(::Type{UniformScaling{T}}) = T