Move math docs out of HelpDB, more examples, fix typos (JuliaLang#17791)

* Move math docs out of HelpDB, more examples, fix typos

Found a series of typos in `cov` and friends. Added more notes
about `NaN` and Julia. Made the function signatures reflect
what's actually in the code. More examples for quite a few
functions.

* Move quadgk docs out, update formatting

* Moved special functions out of HelpDB, insert some links

* Updated docs for some array ops as well

* Updated in response to feedback

Removed calls to `rand` in doctests. Made examples
better. Cleaned up function signatures.

base/abstractarray.jl

@@ -1017,7 +1017,80 @@ function cat_t(catdims, typeC::Type, X...)
  return C
 end
 
+"""
+ vcat(A...)
+
+Concatenate along dimension 1.
+
+```jldoctest
+julia> a = [1 2 3 4 5]
+1×5 Array{Int64,2}:
+ 1 2 3 4 5
+
+julia> b = [6 7 8 9 10; 11 12 13 14 15]
+2×5 Array{Int64,2}:
+ 6 7 8 9 10
+ 11 12 13 14 15
+
+julia> vcat(a,b)
+3×5 Array{Int64,2}:
+ 1 2 3 4 5
+ 6 7 8 9 10
+ 11 12 13 14 15
+
+julia> c = ([1 2 3], [4 5 6])
+(
+[1 2 3],
+<BLANKLINE>
+[4 5 6])
+
+julia> vcat(c...)
+2×3 Array{Int64,2}:
+ 1 2 3
+ 4 5 6
+```
+"""
 vcat(X...) = cat(1, X...)
+"""
+ hcat(A...)
+
+Concatenate along dimension 2.
+
+```jldoctest
+julia> a = [1; 2; 3; 4; 5]
+5-element Array{Int64,1}:
+ 1
+ 2
+ 3
+ 4
+ 5
+
+julia> b = [6 7; 8 9; 10 11; 12 13; 14 15]
+5×2 Array{Int64,2}:
+ 6 7
+ 8 9
+ 10 11
+ 12 13
+ 14 15
+
+julia> hcat(a,b)
+5×3 Array{Int64,2}:
+ 1 6 7
+ 2 8 9
+ 3 10 11
+ 4 12 13
+ 5 14 15
+
+julia> c = ([1; 2; 3], [4; 5; 6])
+([1,2,3],[4,5,6])
+
+julia> hcat(c...)
+3×2 Array{Int64,2}:
+ 1 4
+ 2 5
+ 3 6
+```
+"""
 hcat(X...) = cat(2, X...)
 
 typed_vcat(T::Type, X...) = cat_t(1, T, X...)
@@ -1054,6 +1127,43 @@ function hvcat(nbc::Integer, as...)
  hvcat(ntuple(i->nbc, nbr), as...)
 end
 
+"""
+ hvcat(rows::Tuple{Vararg{Int}}, values...)
+
+Horizontal and vertical concatenation in one call. This function is called for block matrix
+syntax. The first argument specifies the number of arguments to concatenate in each block
+row.
+
+```jldoctest
+julia> a, b, c, d, e, f = 1, 2, 3, 4, 5, 6
+(1,2,3,4,5,6)
+
+julia> [a b c; d e f]
+2×3 Array{Int64,2}:
+ 1 2 3
+ 4 5 6
+
+julia> hvcat((3,3), a,b,c,d,e,f)
+2×3 Array{Int64,2}:
+ 1 2 3
+ 4 5 6
+
+julia> [a b;c d; e f]
+3×2 Array{Int64,2}:
+ 1 2
+ 3 4
+ 5 6
+
+julia> hvcat((2,2,2), a,b,c,d,e,f)
+3×2 Array{Int64,2}:
+ 1 2
+ 3 4
+ 5 6
+```
+
+If the first argument is a single integer `n`, then all block rows are assumed to have `n`
+block columns.
+"""
 hvcat(rows::Tuple{Vararg{Int}}, xs::AbstractMatrix...) = typed_hvcat(promote_eltype(xs...), rows, xs...)
 hvcat{T}(rows::Tuple{Vararg{Int}}, xs::AbstractMatrix{T}...) = typed_hvcat(T, rows, xs...)
 
@@ -1340,8 +1450,7 @@ For multiple iterable arguments, `f` is called elementwise.
 needed, for example in `foreach(println, array)`.
 
 ```jldoctest
-julia> a
-1:3:7
+julia> a = 1:3:7;
 
 julia> foreach(x->println(x^2),a)
 1

base/abstractarraymath.jl

@@ -11,13 +11,55 @@ transpose(a::AbstractArray) = error("transpose not implemented for $(typeof(a)).
 
 ## Constructors ##
 
+"""
+ vec(a::AbstractArray) -> Vector
+
+Reshape array `a` as a one-dimensional column vector.
+
+```jldoctest
+julia> a = [1 2 3; 4 5 6]
+2×3 Array{Int64,2}:
+ 1 2 3
+ 4 5 6
+
+julia> vec(a)
+6-element Array{Int64,1}:
+ 1
+ 4
+ 2
+ 5
+ 3
+ 6
+```
+"""
 vec(a::AbstractArray) = reshape(a,_length(a))
 vec(a::AbstractVector) = a
 
 _sub(::Tuple{}, ::Tuple{}) = ()
 _sub(t::Tuple, ::Tuple{}) = t
 _sub(t::Tuple, s::Tuple) = _sub(tail(t), tail(s))
 
+"""
+ squeeze(A, dims)
+
+Remove the dimensions specified by `dims` from array `A`.
+Elements of `dims` must be unique and within the range `1:ndims(A)`.
+`size(A,i)` must equal 1 for all `i` in `dims`.
+
+```jldoctest
+julia> a = reshape(collect(1:4),(2,2,1,1))
+2×2×1×1 Array{Int64,4}:
+[:, :, 1, 1] =
+ 1 3
+ 2 4
+
+julia> squeeze(a,3)
+2×2×1 Array{Int64,3}:
+[:, :, 1] =
+ 1 3
+ 2 4
+```
+"""
 function squeeze(A::AbstractArray, dims::Dims)
  for i in 1:length(dims)
  1 <= dims[i] <= ndims(A) || throw(ArgumentError("squeezed dims must be in range 1:ndims(A)"))
@@ -71,6 +113,23 @@ function flipdim(A::AbstractVector, d::Integer)
  reverse(A)
 end
 
+"""
+ flipdim(A, d)
+
+Reverse `A` in dimension `d`.
+
+```jldoctest
+julia> b = [1 2; 3 4]
+2×2 Array{Int64,2}:
+ 1 2
+ 3 4
+
+julia> flipdim(b,2)
+2×2 Array{Int64,2}:
+ 2 1
+ 4 3
+```
+"""
 function flipdim(A::AbstractArray, d::Integer)
  nd = ndims(A)
  1 ≤ d ≤ nd || throw(ArgumentError("dimension $d is not 1 ≤ $d ≤ $nd"))
@@ -100,6 +159,36 @@ function flipdim(A::AbstractArray, d::Integer)
 end
 
 circshift(a::AbstractArray, shiftamt::Real) = circshift(a, [Integer(shiftamt)])
+
+"""
+ circshift(A, shifts)
+
+Circularly shift the data in an array. The second argument is a vector giving the amount to
+shift in each dimension.
+
+```jldoctest
+julia> b = reshape(collect(1:16), (4,4))
+4×4 Array{Int64,2}:
+ 1 5 9 13
+ 2 6 10 14
+ 3 7 11 15
+ 4 8 12 16
+
+julia> circshift(b, [0,2])
+4×4 Array{Int64,2}:
+ 9 13 1 5
+ 10 14 2 6
+ 11 15 3 7
+ 12 16 4 8
+
+julia> circshift(b, [-1,0])
+4×4 Array{Int64,2}:
+ 2 6 10 14
+ 3 7 11 15
+ 4 8 12 16
+ 1 5 9 13
+```
+"""
 function circshift{T,N}(a::AbstractArray{T,N}, shiftamts)
  I = ()
  for i=1:N

base/array.jl

@@ -667,6 +667,7 @@ function hcat{T}(V::Vector{T}...)
  end
  return [ V[j][i]::T for i=1:length(V[1]), j=1:length(V) ]
 end
+
 function vcat{T}(arrays::Vector{T}...)
  n = 0
  for a in arrays
@@ -860,7 +861,7 @@ Returns the minimum element and its index.
 The collection must not be empty.
 
 ```jldoctest
-julia> findmax([8,0.1,-9,pi])
+julia> findmin([8,0.1,-9,pi])
 (-9.0,3)
 ```
 """
@@ -915,7 +916,7 @@ vector contains 0 wherever `a` is not a member of `b`.
 ```jldoctest
 julia> a = ['a', 'b', 'c', 'b', 'd', 'a'];
 
-julia> b = ['a','b','c']
+julia> b = ['a','b','c'];
 
 julia> indexin(a,b)
 6-element Array{Int64,1}: