From fabf9e55872f9f8d7c0e6cbada2ccce09e58a2e5 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Tue, 4 Jul 2017 16:17:58 +0200 Subject: [PATCH] add documentation for [Abstract]Vector/[Abstract]Matrix --- base/abstractarray.jl | 7 ++++--- base/array.jl | 23 +++++++++++++++++++++++ base/linalg/rowvector.jl | 2 +- doc/src/devdocs/offset-arrays.md | 2 +- doc/src/manual/arrays.md | 6 +++--- doc/src/manual/performance-tips.md | 2 +- doc/src/stdlib/arrays.md | 4 ++++ 7 files changed, 37 insertions(+), 9 deletions(-) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 63ef9ab76b6ec..5f75a0de5cabf 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -3,9 +3,10 @@ ## Basic functions ## """ - AbstractArray{T, N} + AbstractArray{T,N} -Abstract array supertype which arrays inherit from. +Abstract `N`-dimensional array supertype containing elements of type `T`. +[`Array`](@ref)s and some array-like objects inherit from this type. """ AbstractArray @@ -877,7 +878,7 @@ end getindex(A, inds...) Return a subset of array `A` as specified by `inds`, where each `ind` may be an -`Int`, a `Range`, or a `Vector`. See the manual section on +`Int`, a `Range`, or a [`Vector`](@ref). See the manual section on [array indexing](@ref man-array-indexing) for details. # Examples diff --git a/base/array.jl b/base/array.jl index 56664a53ae4d4..ed66d51716f2a 100644 --- a/base/array.jl +++ b/base/array.jl @@ -3,8 +3,20 @@ ## array.jl: Dense arrays ## Type aliases for convenience ## +""" + AbstractVector{T} +Abstract vector supertype containing elements of type `T`. +Alias for [`AbstractArray{T,1}`](@ref). +""" const AbstractVector{T} = AbstractArray{T,1} + +""" + AbstractMatrix{T} + +Abstract matrix supertype containing elements of type `T`. +Alias for [`AbstractArray{T,2}`](@ref). +""" const AbstractMatrix{T} = AbstractArray{T,2} const AbstractVecOrMat{T} = Union{AbstractVector{T}, AbstractMatrix{T}} const RangeIndex = Union{Int, Range{Int}, AbstractUnitRange{Int}} @@ -13,7 +25,18 @@ const IntOrInd = Union{Int, AbstractUnitRange} const DimsOrInds{N} = NTuple{N,DimOrInd} const NeedsShaping = Union{Tuple{Integer,Vararg{Integer}}, Tuple{OneTo,Vararg{OneTo}}} +""" + Vector{T} + +Vector type containing elements of type `T`. Alias for [`Array{T,1}`](@ref). +""" const Vector{T} = Array{T,1} + +""" + Matrix{T} + +Matrix type containing elements of type `T`. Alias for [`Array{T,2}`](@ref). +""" const Matrix{T} = Array{T,2} const VecOrMat{T} = Union{Vector{T}, Matrix{T}} diff --git a/base/linalg/rowvector.jl b/base/linalg/rowvector.jl index ae04639f505a2..11f75490ae9a3 100644 --- a/base/linalg/rowvector.jl +++ b/base/linalg/rowvector.jl @@ -3,7 +3,7 @@ """ RowVector(vector) -A lazy-view wrapper of an `AbstractVector`, which turns a length-`n` vector into a `1×n` +A lazy-view wrapper of an [`AbstractVector`](@ref), which turns a length-`n` vector into a `1×n` shaped row vector and represents the transpose of a vector (the elements are also transposed recursively). This type is usually constructed (and unwrapped) via the [`transpose`](@ref) function or `.'` operator (or related [`ctranspose`](@ref) or `'` operator). diff --git a/doc/src/devdocs/offset-arrays.md b/doc/src/devdocs/offset-arrays.md index 689f856b48d62..9a8fe083421d5 100644 --- a/doc/src/devdocs/offset-arrays.md +++ b/doc/src/devdocs/offset-arrays.md @@ -77,7 +77,7 @@ can sometimes simplify such tests. Some algorithms are most conveniently (or efficiently) written in terms of a single linear index, `A[i]` even if `A` is multi-dimensional. In "true" linear indexing, the indices always range -from `1:length(A)`. However, this raises an ambiguity for one-dimensional arrays (a.k.a., `AbstractVector`): +from `1:length(A)`. However, this raises an ambiguity for one-dimensional arrays (a.k.a., [`AbstractVector`](@ref)): does `v[i]` mean linear indexing, or Cartesian indexing with the array's native indices? For this reason, if you want to use linear indexing in an algorithm, your best option is to get diff --git a/doc/src/manual/arrays.md b/doc/src/manual/arrays.md index 755c66e9fc343..ecdcf33cb3855 100644 --- a/doc/src/manual/arrays.md +++ b/doc/src/manual/arrays.md @@ -617,8 +617,8 @@ julia> string.(1:3, ". ", ["First", "Second", "Third"]) ### Implementation -The base array type in Julia is the abstract type `AbstractArray{T,N}`. It is parametrized by -the number of dimensions `N` and the element type `T`. `AbstractVector` and `AbstractMatrix` are +The base array type in Julia is the abstract type [`AbstractArray{T,N}`](@ref). It is parametrized by +the number of dimensions `N` and the element type `T`. [`AbstractVector`](@ref) and [`AbstractMatrix`](@ref) are aliases for the 1-d and 2-d cases. Operations on `AbstractArray` objects are defined using higher level operators and functions, in a way that is independent of the underlying storage. These operations generally work correctly as a fallback for any specific array implementation. @@ -644,7 +644,7 @@ method [`Base.unsafe_convert(Ptr{T}, A)`](@ref) is provided, the memory layout s in the same way to these strides. The [`Array`](@ref) type is a specific instance of `DenseArray` where elements are stored in column-major -order (see additional notes in [Performance Tips](@ref man-performance-tips)). `Vector` and `Matrix` are aliases for +order (see additional notes in [Performance Tips](@ref man-performance-tips)). [`Vector`](@ref) and [`Matrix`](@ref) are aliases for the 1-d and 2-d cases. Specific operations such as scalar indexing, assignment, and a few other basic storage-specific operations are all that have to be implemented for [`Array`](@ref), so that the rest of the array library can be implemented in a generic manner. diff --git a/doc/src/manual/performance-tips.md b/doc/src/manual/performance-tips.md index 7eec3d59137b8..073d2d9410d60 100644 --- a/doc/src/manual/performance-tips.md +++ b/doc/src/manual/performance-tips.md @@ -806,7 +806,7 @@ is that with column-major arrays, the first index changes most rapidly. Essentia that looping will be faster if the inner-most loop index is the first to appear in a slice expression. Consider the following contrived example. Imagine we wanted to write a function that accepts a -`Vector` and returns a square `Matrix` with either the rows or the columns filled with copies +[`Vector`](@ref) and returns a square [`Matrix`](@ref) with either the rows or the columns filled with copies of the input vector. Assume that it is not important whether rows or columns are filled with these copies (perhaps the rest of the code can be easily adapted accordingly). We could conceivably do this in at least four ways (in addition to the recommended call to the built-in [`repmat()`](@ref)): diff --git a/doc/src/stdlib/arrays.md b/doc/src/stdlib/arrays.md index 0ebf17bf044d1..692ac5387cbd6 100644 --- a/doc/src/stdlib/arrays.md +++ b/doc/src/stdlib/arrays.md @@ -4,7 +4,11 @@ ```@docs Core.AbstractArray +Base.AbstractVector +Base.AbstractMatrix Core.Array +Base.Vector +Base.Matrix Base.getindex(::Type, ::Any...) Base.zeros Base.ones