diff --git a/docs/src/index.md b/docs/src/index.md
index 075b6069..7772aee8 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -4,9 +4,9 @@
[](https://travis-ci.org/JuliaArrays/BlockArrays.jl) [](https://codecov.io/gh/JuliaArrays/BlockArrays.jl)
-A block array is a partition of an array into multiple blocks or subarrays, see [wikipedia](https://en.wikipedia.org/wiki/Block_matrix) for a more extensive description. This package has two purposes. Firstly, it defines an interface for an `AbstractBlockArray` block arrays that can be shared among types representing different types of block arrays. The advantage to this is that it provides a consistent API for block arrays.
+A block array is a partition of an array into multiple blocks or subarrays, see [wikipedia](https://en.wikipedia.org/wiki/Block_matrix) for a more extensive description. This package has two purposes. Firstly, it defines an interface for an [`AbstractBlockArray`](@ref) block arrays that can be shared among types representing different types of block arrays. The advantage to this is that it provides a consistent API for block arrays.
-Secondly, it also implements two concrete types of block arrays that follow the `AbstractBlockArray` interface. The type `BlockArray` stores each single block contiguously, by wrapping an `AbstractArray{<:AbstractArray{T,N},N}` to concatenate all blocks – the complete array is thus not stored contiguously. Conversely, a `BlockedArray` stores the full matrix contiguously (by wrapping only one `AbstractArray{T, N}`) and only superimposes a block structure. This means that `BlockArray` supports fast non copying extraction and insertion of blocks, while `BlockedArray` supports fast access to the full matrix to use in, for example, a linear solver.
+Secondly, it also implements two concrete types of block arrays that follow [`AbstractBlockArray` interface](@ref abstract_block_array_interface). The type [`BlockArray`](@ref) stores each single block contiguously, by wrapping an `AbstractArray{<:AbstractArray{T,N},N}` to concatenate all blocks – the complete array is thus not stored contiguously. Conversely, a [`BlockedArray`](@ref) stores the full matrix contiguously (by wrapping only one `AbstractArray{T, N}`) and only superimposes a block structure. This means that `BlockArray` supports fast non copying extraction and insertion of blocks, while `BlockedArray` supports fast access to the full matrix to use in, for example, a linear solver.
## Terminology
diff --git a/docs/src/man/abstractblockarrayinterface.md b/docs/src/man/abstractblockarrayinterface.md
index 33f347ad..83f3f0b9 100644
--- a/docs/src/man/abstractblockarrayinterface.md
+++ b/docs/src/man/abstractblockarrayinterface.md
@@ -6,15 +6,14 @@ are typically `BlockedOneTo`s, but may also be standard and non-blocked `Abstrac
the block axis interface.
-| Methods to implement | Brief description |
-| :---------------------- | :---------------- |
-| `blockaxes(A)` | A one-tuple returning a range of blocks specifying the block structure |
-| `getindex(A, K::Block{1})` | return a unit range of indices in the specified block |
-| `blocklasts(A)` | Returns the last index of each block |
-| `findblock(A, k)` | return the block that contains the `k`th entry of `A`
+| Methods to implement | Brief description |
+| :------------------------- | :--------------------------------------------------------------------- |
+| `blockaxes(A)` | A one-tuple returning a range of blocks specifying the block structure |
+| `getindex(A, K::Block{1})` | Returns a unit range of indices in the specified block |
+| `blocklasts(A)` | Returns the last index of each block |
+| `findblock(A, k)` | Returns the block that contains the `k`th entry of `A` |
-
-# The `AbstractBlockArray` interface
+# [The `AbstractBlockArray` interface](@id abstract_block_array_interface)
An arrays block structure is inferred from an axes, and therefore every array
is in some sense already a block array:
@@ -37,10 +36,9 @@ julia> A[Block(1,1)]
```
It is possible to override additional functions to improve speed, however.
-| Methods to implement | Brief description |
-| :---------------------- | :---------------- |
-| **Optional methods** |
-| `BlockArrays.viewblock(A, i::Block)` | Specialised non-allocating `X[Block(i...)]`, blocked indexing |
+| Optional methods | Default definition | Brief description |
+| :----------------------------------- | :------------------------------------------------- | :------------------------------------------------------------ |
+| `BlockArrays.viewblock(A, i::Block)` | defined in terms `Base.view` and the block indices | Specialised non-allocating `X[Block(i...)]`, blocked indexing |
For a more thorough description of the methods see the public interface documentation.
diff --git a/src/abstractblockarray.jl b/src/abstractblockarray.jl
index eceb4023..faf58cd5 100644
--- a/src/abstractblockarray.jl
+++ b/src/abstractblockarray.jl
@@ -3,23 +3,29 @@
####################################
"""
- abstract AbstractBlockArray{T, N} <: AbstractArray{T, N}
-
-The abstract type that represents a blocked array. Types that implement
-the `AbstractBlockArray` interface should subtype from this type.
-
-** Typealiases **
+ AbstractBlockArray{T, N} <: AbstractArray{T, N}
+Supertype for `N`-dimensional block arrays with elements of type `T`. [`BlockedArray`](@ref), [`BlockArray`](@ref) and other types are subtypes of this. See the manual section on the
+the `AbstractBlockArray` interface.
+"""
+abstract type AbstractBlockArray{T,N} <: LayoutArray{T,N} end
-* `AbstractBlockMatrix{T}` -> `AbstractBlockArray{T, 2}`
+"""
+ AbstractBlockMatrix{T}
+Supertype for two-dimensional block arrays with elements of type `T`. Alias for [`AbstractBlockArray{T,2}`](@ref).
+"""
+const AbstractBlockMatrix{T} = AbstractBlockArray{T,2}
-* `AbstractBlockVector{T}` -> `AbstractBlockArray{T, 1}`
+"""
+ AbstractBlockVector{T}
+Supertype for one-dimensional block arrays with elements of type `T`. Alias for [`AbstractBlockArray{T,1}`](@ref).
+"""
+const AbstractBlockVector{T} = AbstractBlockArray{T,1}
-* `AbstractBlockVecOrMat{T}` -> `Union{AbstractBlockMatrix{T}, AbstractBlockVector{T}}`
"""
-abstract type AbstractBlockArray{T, N} <: LayoutArray{T, N} end
-const AbstractBlockMatrix{T} = AbstractBlockArray{T, 2}
-const AbstractBlockVector{T} = AbstractBlockArray{T, 1}
-const AbstractBlockVecOrMat{T} = Union{AbstractBlockMatrix{T}, AbstractBlockVector{T}}
+ AbstractVecOrMat{T}
+Union type of [`AbstractBlockMatrix`](@ref) and [`AbstractBlockVector`](@ref).
+"""
+const AbstractBlockVecOrMat{T} = Union{AbstractBlockMatrix{T},AbstractBlockVector{T}}
block2string(b, s) = string(join(map(string,b), '×'), "-blocked ", Base.dims2string(s))
_block_summary(a) = string(block2string(blocksize(a), size(a)), " ", typeof(a))