Update the docstring for OffsetArray (#176)

Rename fill to fill1d in benchmarks

Author: jishnub

benchmark/benchmarks.jl

@@ -8,7 +8,7 @@ y = OffsetArray{Float64}(undef, -dim + 1 : dim)
 x2d = Array{Float64}(undef, 2*dim, 2*dim)
 y2d = OffsetArray{Float64}(undef, -dim + 1 : dim, -dim + 1 : dim)
 
-fill(x) = for i in axes(x,1); x[i] = i; end
+fill1d(x) = for i in axes(x,1); x[i] = i; end
 fill2d(x) = for j in axes(x,2); for i in axes(x,1); x[i,j] = i + j; end; end
 update(x) = for i in axes(x,1); x[i] = x[i] + i; end
 update2d(x) = for j in axes(x,2); for i in axes(x,1); x[i,j] = x[i,j] + i + j; end; end
@@ -20,8 +20,8 @@ unsafe_update(x) = @inbounds(for i in axes(x,1); x[i] = x[i] + i; end)
 unsafe_update2d(x) = @inbounds(for j in axes(x,2); for i in axes(x,1); x[i,j] = x[i,j] + i + j; end; end)
 unsafe_update_eachindex(x) = @inbounds(for i in eachindex(x); x[i] = x[i] + i; end)
 
-@show @benchmark fill(x)
-@show @benchmark fill(y)
+@show @benchmark fill1d(x)
+@show @benchmark fill1d(y)
 @show @benchmark fill2d(x2d)
 @show @benchmark fill2d(y2d)
 @show @benchmark update(x)

src/OffsetArrays.jl

@@ -23,8 +23,17 @@ const ArrayInitializer = Union{UndefInitializer, Missing, Nothing}
 """
     OffsetArray(A, indices...)
 
-Return an `AbstractArray` that shares element type and size with the first argument, but
-used the given `indices`, which are checked for compatible size.
+Return an `AbstractArray` that shares element type and size with the first argument but
+uses the supplied `indices` to infer its axes. If all the indices are `AbstractUnitRange`s then 
+these are directly used as the axis span along each dimension. Refer to the examples below for other 
+permissible types.
+
+Alternatively it's possible to specify the coordinates of one corner of the array 
+and have the axes be computed automatically from the size of `A`. 
+This constructor makes it convenient to shift to
+an arbitrary starting index along each axis, for example to a zero-based indexing scheme followed by 
+arrays in languages such as C and Python.
+See [`Origin`](@ref) and the examples below for this usage.
 
 # Example: offsets
 
@@ -42,27 +51,33 @@ julia> A[0, 1]
 5
 ```
 
-Examples of range-like types are: `Colon()`(aka `:`), `UnitRange`(e.g, `-1:2`), and
-`CartesianIndices`.
+Examples of range-like types are: `UnitRange` (e.g, `-1:2`), `CartesianIndices`, 
+and `Colon()` (or concisely `:`). A `UnitRange` specifies the axis span along one particular dimension, 
+`CartesianIndices` specify the axis spans along multiple dimensions, and a `Colon` is a placeholder 
+that specifies that the `OffsetArray` shares its axis with its parent along that dimension.
 
 ```jldoctest; setup=:(using OffsetArrays)
 julia> OffsetArray(reshape(1:6, 2, 3), 0:1, -1:1)
 2×3 OffsetArray(reshape(::UnitRange{$Int}, 2, 3), 0:1, -1:1) with eltype $Int with indices 0:1×-1:1:
  1  3  5
  2  4  6
 
-julia> OffsetArray(reshape(1:6, 2, 3), :, -1:1) # : as a placeholder to indicate that no offset is to be applied to this dimension
+julia> OffsetArray(reshape(1:6, 2, 3), :, -1:1) # : as a placeholder to indicate that no offset is to be applied to the first dimension
 2×3 OffsetArray(reshape(::UnitRange{$Int}, 2, 3), 1:2, -1:1) with eltype $Int with indices 1:2×-1:1:
  1  3  5
  2  4  6
+```
+
+Use `CartesianIndices` to specify the coordinates of two diagonally opposite corners:
 
+```jldoctest; setup=:(using OffsetArrays)
 julia> OffsetArray(reshape(1:6, 2, 3), CartesianIndex(0, -1):CartesianIndex(1, 1))
 2×3 OffsetArray(reshape(::UnitRange{$Int}, 2, 3), 0:1, -1:1) with eltype $Int with indices 0:1×-1:1:
  1  3  5
  2  4  6
 ```
 
-Integers and range-like types can't be used interchangebly:
+Integers and range-like types may not be combined in the same call:
 
 ```julia
 julia> OffsetArray(reshape(1:6, 2, 3), 0, -1:1)
@@ -71,7 +86,10 @@ ERROR: [...]
 
 # Example: origin
 
-[`OffsetArrays.Origin`](@ref) can be used to directly specify the origin of the output OffsetArray.
+[`OffsetArrays.Origin`](@ref) may be used to specify the origin of the OffsetArray. The term origin here 
+refers to the corner with the lowest values of coordinates, such as the left edge for an `AbstractVector`, 
+the bottom left corner for an `AbstractMatrix` and so on. The coordinates of the origin sets the starting 
+index of the array along each dimension.
 
 ```jldoctest; setup=:(using OffsetArrays)
 julia> a = [1 2; 3 4];
@@ -81,7 +99,7 @@ julia> OffsetArray(a, OffsetArrays.Origin(0, 1))
  1  2
  3  4
 
-julia> OffsetArray(a, OffsetArrays.Origin(0)) # short notation for `Origin(0, ..., 0)`
+julia> OffsetArray(a, OffsetArrays.Origin(0)) # set the origin to zero along each dimension
 2×2 OffsetArray(::$(Array{Int, 2}), 0:1, 0:1) with eltype $Int with indices 0:1×0:1:
  1  2
  3  4
@@ -279,7 +297,7 @@ end
 
 @inline function Base.setindex!(A::OffsetArray{T,N}, val, I::Vararg{Int,N}) where {T,N}
     @boundscheck checkbounds(A, I...)
-    J = @inbounds map(parentindex, axes(A), I)
+    J = map(parentindex, axes(A), I)
     @inbounds parent(A)[J...] = val
     A
 end