Move some docstrings from helpdb to function definitions

base/abstractarray.jl

@@ -858,6 +858,16 @@ end
 # note: the following type definitions don't mean any AbstractArray is convertible to
 # a data Ref. they just map the array element type to the pointer type for
 # convenience in cases that work.
+
+"""
+    pointer(array [, index])
+
+Get the native address of an array or string element. Be careful to ensure that a Julia
+reference to `a` exists as long as this pointer will be used. This function is "unsafe" like
+`unsafe_convert`.
+
+Calling `Ref(array[, index])` is generally preferable to this function.
+"""
 pointer(x::AbstractArray{T}) where {T} = unsafe_convert(Ptr{T}, x)
 function pointer(x::AbstractArray{T}, i::Integer) where T
     @_inline_meta

base/array.jl

@@ -212,6 +212,37 @@ function getindex(::Type{Any}, vals::ANY...)
 end
 getindex(::Type{Any}) = Array{Any,1}(0)
 
+"""
+    fill!(A, x)
+
+Fill array `A` with the value `x`. If `x` is an object reference, all elements will refer to
+the same object. `fill!(A, Foo())` will return `A` filled with the result of evaluating
+`Foo()` once.
+
+```jldoctest
+julia> A = zeros(2,3)
+2×3 Array{Float64,2}:
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+
+julia> fill!(A, 2.)
+2×3 Array{Float64,2}:
+ 2.0  2.0  2.0
+ 2.0  2.0  2.0
+
+julia> a = [1, 1, 1]; A = fill!(Vector{Vector{Int}}(3), a); a[1] = 2; A
+3-element Array{Array{Int64,1},1}:
+ [2, 1, 1]
+ [2, 1, 1]
+ [2, 1, 1]
+
+julia> x = 0; f() = (global x += 1; x); fill!(Vector{Int}(3), f())
+3-element Array{Int64,1}:
+ 1
+ 1
+ 1
+```
+"""
 function fill!(a::Union{Array{UInt8}, Array{Int8}}, x::Integer)
     ccall(:memset, Ptr{Void}, (Ptr{Void}, Cint, Csize_t), a, x, length(a))
     return a

base/boot.jl

@@ -208,6 +208,12 @@ struct DomainError        <: Exception end
 struct OverflowError      <: Exception end
 struct InexactError       <: Exception end
 struct OutOfMemoryError   <: Exception end
+
+"""
+    ReadOnlyMemoryError()
+
+An operation tried to write to memory that is read-only.
+"""
 struct ReadOnlyMemoryError<: Exception end
 struct SegmentationFault  <: Exception end
 struct StackOverflowError <: Exception end

base/docs/helpdb/Base.jl

@@ -2,66 +2,6 @@
 
 # Base
 
-"""
-    fill!(A, x)
-
-Fill array `A` with the value `x`. If `x` is an object reference, all elements will refer to
-the same object. `fill!(A, Foo())` will return `A` filled with the result of evaluating
-`Foo()` once.
-
-```jldoctest
-julia> A = zeros(2,3)
-2×3 Array{Float64,2}:
- 0.0  0.0  0.0
- 0.0  0.0  0.0
-
-julia> fill!(A, 2.)
-2×3 Array{Float64,2}:
- 2.0  2.0  2.0
- 2.0  2.0  2.0
-
-julia> a = [1, 1, 1]; A = fill!(Vector{Vector{Int}}(3), a); a[1] = 2; A
-3-element Array{Array{Int64,1},1}:
- [2, 1, 1]
- [2, 1, 1]
- [2, 1, 1]
-
-julia> x = 0; f() = (global x += 1; x); fill!(Vector{Int}(3), f())
-3-element Array{Int64,1}:
- 1
- 1
- 1
-```
-"""
-fill!
-
-"""
-    read!(stream::IO, array::Union{Array, BitArray})
-    read!(filename::AbstractString, array::Union{Array, BitArray})
-
-Read binary data from an I/O stream or file, filling in `array`.
-"""
-read!
-
-"""
-    pointer(array [, index])
-
-Get the native address of an array or string element. Be careful to ensure that a Julia
-reference to `a` exists as long as this pointer will be used. This function is "unsafe" like
-`unsafe_convert`.
-
-Calling `Ref(array[, index])` is generally preferable to this function.
-"""
-pointer
-
-"""
-    precision(num::AbstractFloat)
-
-Get the precision of a floating point number, as defined by the effective number of bits in
-the mantissa.
-"""
-precision
-
 """
     -(x)
 
@@ -174,14 +114,6 @@ Neither `convert` nor `cconvert` should take a Julia object and turn it into a `
 """
 cconvert
 
-"""
-    assert(cond)
-
-Throw an [`AssertionError`](@ref) if `cond` is `false`.
-Also available as the macro `@assert expr`.
-"""
-assert
-
 """
     sech(x)
 
@@ -346,13 +278,6 @@ Stacktrace:
 """
 sizeof(::Type)
 
-"""
-    ReadOnlyMemoryError()
-
-An operation tried to write to memory that is read-only.
-"""
-ReadOnlyMemoryError
-
 """
     ceil([T,] x, [digits, [base]])
 

base/error.jl

@@ -65,6 +65,12 @@ systemerror(p, b::Bool; extrainfo=nothing) = b ? throw(Main.Base.SystemError(str
 
 ## assertion functions and macros ##
 
+"""
+    assert(cond)
+
+Throw an [`AssertionError`](@ref) if `cond` is `false`.
+Also available as the macro `@assert expr`.
+"""
 assert(x) = x ? nothing : throw(Main.Base.AssertionError())
 macro assert(ex, msgs...)
     msg = isempty(msgs) ? ex : msgs[1]

base/float.jl

@@ -561,10 +561,17 @@ hash(x::Union{Bool,Int8,UInt8,Int16,UInt16,Int32,UInt32}, h::UInt) = hash(Int64(
 hash(x::Float32, h::UInt) = hash(Float64(x), h)
 
 ## precision, as defined by the effective number of bits in the mantissa ##
+
+"""
+    precision(num::AbstractFloat)
+
+Get the precision of a floating point number, as defined by the effective number of bits in
+the mantissa.
+"""
+precision(::T) where {T<:AbstractFloat} = precision(T)
 precision(::Type{Float16}) = 11
 precision(::Type{Float32}) = 24
 precision(::Type{Float64}) = 53
-precision(::T) where {T<:AbstractFloat} = precision(T)
 
 """
     uabs(x::Integer)

base/io.jl

@@ -384,22 +384,6 @@ to return.
 """
 read(s::IO, ::Type{T}, dims::Dims) where {T} = read!(s, Array{T}(dims))
 
-@noinline function read!(s::IO, a::Array{UInt8}) # mark noinline to ensure the array is gc-rooted somewhere (by the caller)
-    unsafe_read(s, pointer(a), sizeof(a))
-    return a
-end
-
-@noinline function read!(s::IO, a::Array{T}) where T # mark noinline to ensure the array is gc-rooted somewhere (by the caller)
-    if isbits(T)
-        unsafe_read(s, pointer(a), sizeof(a))
-    else
-        for i in eachindex(a)
-            a[i] = read(s, T)
-        end
-    end
-    return a
-end
-
 function read(s::IO, ::Type{Char})
     ch = read(s, UInt8)
     if ch < 0x80
@@ -419,6 +403,28 @@ function read(s::IO, ::Type{Char})
     return Char(c)
 end
 
+"""
+    read!(stream::IO, array::Union{Array, BitArray})
+    read!(filename::AbstractString, array::Union{Array, BitArray})
+
+Read binary data from an I/O stream or file, filling in `array`.
+"""
+@noinline function read!(s::IO, a::Array{T}) where T # mark noinline to ensure the array is gc-rooted somewhere (by the caller)
+    if isbits(T)
+        unsafe_read(s, pointer(a), sizeof(a))
+    else
+        for i in eachindex(a)
+            a[i] = read(s, T)
+        end
+    end
+    return a
+end
+
+@noinline function read!(s::IO, a::Array{UInt8}) # mark noinline to ensure the array is gc-rooted somewhere (by the caller)
+    unsafe_read(s, pointer(a), sizeof(a))
+    return a
+end
+
 # readuntil_string is useful below since it has
 # an optimized method for s::IOStream
 readuntil_string(s::IO, delim::UInt8) = String(readuntil(s, delim))