Move array documentation out of HelpDB, add examples (#17795)

Lots of examples for things that are probably confusing for new
Julia users. Made `reducedim` and `mapreducedim` arguments more
similar to the ones for `reduce` and `mapreduce`.

Author: kshyatt

base/abstractarray.jl

@@ -1358,6 +1358,49 @@ foreach(f, itrs...) = (for z in zip(itrs...); f(z...); end; nothing)
 ## transform any set of dimensions
 ## dims specifies which dimensions will be transformed. for example
 ## dims==1:2 will call f on all slices A[:,:,...]
+"""
+    mapslices(f, A, dims)
+
+Transform the given dimensions of array `A` using function `f`. `f` is called on each slice
+of `A` of the form `A[...,:,...,:,...]`. `dims` is an integer vector specifying where the
+colons go in this expression. The results are concatenated along the remaining dimensions.
+For example, if `dims` is `[1,2]` and `A` is 4-dimensional, `f` is called on `A[:,:,i,j]`
+for all `i` and `j`.
+
+```jldoctest
+julia> a = reshape(collect(1:16),(2,2,2,2))
+2×2×2×2 Array{Int64,4}:
+[:, :, 1, 1] =
+ 1  3
+ 2  4
+<BLANKLINE>
+[:, :, 2, 1] =
+ 5  7
+ 6  8
+<BLANKLINE>
+[:, :, 1, 2] =
+  9  11
+ 10  12
+<BLANKLINE>
+[:, :, 2, 2] =
+ 13  15
+ 14  16
+
+julia> mapslices(sum, a, [1,2])
+1×1×2×2 Array{Int64,4}:
+[:, :, 1, 1] =
+ 10
+<BLANKLINE>
+[:, :, 2, 1] =
+ 26
+<BLANKLINE>
+[:, :, 1, 2] =
+ 42
+<BLANKLINE>
+[:, :, 2, 2] =
+ 58
+```
+"""
 mapslices(f, A::AbstractArray, dims) = mapslices(f, A, [dims...])
 function mapslices(f, A::AbstractArray, dims::AbstractVector)
     if isempty(dims)

base/arraymath.jl

@@ -159,6 +159,23 @@ function flipdim{T}(A::Array{T}, d::Integer)
     return B
 end
 
+"""
+    rotl90(A)
+
+Rotate matrix `A` left 90 degrees.
+
+```jldoctest
+julia> a = [1 2; 3 4]
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+
+julia> rotl90(a)
+2×2 Array{Int64,2}:
+ 2  4
+ 1  3
+```
+"""
 function rotl90(A::AbstractMatrix)
     ind1, ind2 = indices(A)
     B = similar(A, (ind2,ind1))
@@ -168,6 +185,24 @@ function rotl90(A::AbstractMatrix)
     end
     return B
 end
+
+"""
+    rotr90(A)
+
+Rotate matrix `A` right 90 degrees.
+
+```jldoctest
+julia> a = [1 2; 3 4]
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+
+julia> rotr90(a)
+2×2 Array{Int64,2}:
+ 3  1
+ 4  2
+```
+"""
 function rotr90(A::AbstractMatrix)
     ind1, ind2 = indices(A)
     B = similar(A, (ind2,ind1))
@@ -177,6 +212,23 @@ function rotr90(A::AbstractMatrix)
     end
     return B
 end
+"""
+    rot180(A)
+
+Rotate matrix `A` 180 degrees.
+
+```jldoctest
+julia> a = [1 2; 3 4]
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+
+julia> rot180(a)
+2×2 Array{Int64,2}:
+ 4  3
+ 2  1
+```
+"""
 function rot180(A::AbstractMatrix)
     B = similar(A)
     ind1, ind2 = indices(A,1), indices(A,2)
@@ -186,13 +238,102 @@ function rot180(A::AbstractMatrix)
     end
     return B
 end
+"""
+    rotl90(A, k)
+
+Rotate matrix `A` left 90 degrees an integer `k` number of times.
+If `k` is zero or a multiple of four, this is equivalent to a `copy`.
+
+```jldoctest
+julia> a = [1 2; 3 4]
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+
+julia> rotl90(a,1)
+2×2 Array{Int64,2}:
+ 2  4
+ 1  3
+
+julia> rotl90(a,2)
+2×2 Array{Int64,2}:
+ 4  3
+ 2  1
+
+julia> rotl90(a,3)
+2×2 Array{Int64,2}:
+ 3  1
+ 4  2
+
+julia> rotl90(a,4)
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+```
+"""
 function rotl90(A::AbstractMatrix, k::Integer)
     k = mod(k, 4)
     k == 1 ? rotl90(A) :
     k == 2 ? rot180(A) :
     k == 3 ? rotr90(A) : copy(A)
 end
+"""
+    rotr90(A, k)
+
+Rotate matrix `A` right 90 degrees an integer `k` number of times. If `k` is zero or a
+multiple of four, this is equivalent to a `copy`.
+
+```jldoctest
+julia> a = [1 2; 3 4]
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+
+julia> rotr90(a,1)
+2×2 Array{Int64,2}:
+ 3  1
+ 4  2
+
+julia> rotr90(a,2)
+2×2 Array{Int64,2}:
+ 4  3
+ 2  1
+
+julia> rotr90(a,3)
+2×2 Array{Int64,2}:
+ 2  4
+ 1  3
+
+julia> rotr90(a,4)
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+```
+"""
 rotr90(A::AbstractMatrix, k::Integer) = rotl90(A,-k)
+"""
+    rot180(A, k)
+
+Rotate matrix `A` 180 degrees an integer `k` number of times.
+If `k` is even, this is equivalent to a `copy`.
+
+```jldoctest
+julia> a = [1 2; 3 4]
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+
+julia> rot180(a,1)
+2×2 Array{Int64,2}:
+ 4  3
+ 2  1
+
+julia> rot180(a,2)
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+```
+"""
 rot180(A::AbstractMatrix, k::Integer) = mod(k, 2) == 1 ? rot180(A) : copy(A)
 
 ## Transpose ##

base/docs/helpdb/Base.jl

@@ -490,19 +490,6 @@ Get a backtrace object for the current program point.
 """
 backtrace
 
-"""
-    reducedim(f, A, dims[, initial])
-
-Reduce 2-argument function `f` along dimensions of `A`. `dims` is a vector specifying the
-dimensions to reduce, and `initial` is the initial value to use in the reductions. For `+`, `*`,
-`max` and `min` the `initial` argument is optional.
-
-The associativity of the reduction is implementation-dependent; if you need a particular
-associativity, e.g. left-to-right, you should write your own loop. See documentation for
-`reduce`.
-"""
-reducedim
-
 """
     -(x)
 
@@ -1105,17 +1092,6 @@ representable.
 """
 ceil
 
-"""
-    mapslices(f, A, dims)
-
-Transform the given dimensions of array `A` using function `f`. `f` is called on each slice
-of `A` of the form `A[...,:,...,:,...]`. `dims` is an integer vector specifying where the
-colons go in this expression. The results are concatenated along the remaining dimensions.
-For example, if `dims` is `[1,2]` and `A` is 4-dimensional, `f` is called on `A[:,:,i,j]`
-for all `i` and `j`.
-"""
-mapslices
-
 """
     issocket(path) -> Bool
 
@@ -2321,15 +2297,6 @@ Bessel function of the second kind of order 1, ``Y_1(x)``.
 """
 bessely1
 
-"""
-    cumprod(A, [dim])
-
-Cumulative product along a dimension `dim` (defaults to 1). See also
-[`cumprod!`](:func:`cumprod!`) to use a preallocated output array, both for performance and
-to control the precision of the output (e.g. to avoid overflow).
-"""
-cumprod
-
 """
     besseljx(nu, x)
 
@@ -3054,21 +3021,6 @@ block to create a new scope with copies of all variables referenced in the expre
 """
 :@async
 
-"""
-    rotr90(A)
-
-Rotate matrix `A` right 90 degrees.
-"""
-rotr90(A)
-
-"""
-    rotr90(A, k)
-
-Rotate matrix `A` right 90 degrees an integer `k` number of times. If `k` is zero or a
-multiple of four, this is equivalent to a `copy`.
-"""
-rotr90(A, k)
-
 """
     readdir([dir]) -> Vector{String}
 
@@ -3523,21 +3475,6 @@ Number of ways to choose `k` out of `n` items.
 """
 binomial
 
-"""
-    rot180(A)
-
-Rotate matrix `A` 180 degrees.
-"""
-rot180(A)
-
-"""
-    rot180(A, k)
-
-Rotate matrix `A` 180 degrees an integer `k` number of times. If `k` is even, this is
-equivalent to a `copy`.
-"""
-rot180(A, k)
-
 """
     .<=(x, y)
     .≤(x,y)
@@ -3903,21 +3840,6 @@ x == div(x,y)*y + rem(x,y)
 """
 rem
 
-"""
-    rotl90(A)
-
-Rotate matrix `A` left 90 degrees.
-"""
-rotl90(A)
-
-"""
-    rotl90(A, k)
-
-Rotate matrix `A` left 90 degrees an integer `k` number of times. If `k` is zero or a
-multiple of four, this is equivalent to a `copy`.
-"""
-rotl90(A, k)
-
 """
     info(msg)
 
@@ -5623,14 +5545,6 @@ handle comparison to other types via promotion rules where possible.
 """
 Base.:(==)
 
-"""
-    mapreducedim(f, op, A, dims[, initial])
-
-Evaluates to the same as `reducedim(op, map(f, A), dims, f(initial))`, but is generally
-faster because the intermediate array is avoided.
-"""
-mapreducedim
-
 """
     seekstart(s)
 
@@ -6415,15 +6329,6 @@ the group owning the file
 """
 operm
 
-"""
-    cumsum(A, [dim])
-
-Cumulative sum along a dimension `dim` (defaults to 1). See also [`cumsum!`](:func:`cumsum!`)
-to use a preallocated output array, both for performance and to control the precision of the
-output (e.g. to avoid overflow).
-"""
-cumsum
-
 """
     rpad(string, n, p)