Update docstrings (#271)

* Update docstrings

* remove missed doctest setup

* Add doctests

* Update blockproduct.jl

* fix blockvec result summary

* validate doctests only on v1.9+ in tests

Author: jishnub

docs/make.jl

@@ -3,10 +3,11 @@ using Documenter, BlockArrays
 # Build documentation.
 # ====================
 
+DocMeta.setdocmeta!(BlockArrays, :DocTestSetup, :(using BlockArrays); recursive=true)
+
 makedocs(
     modules = [BlockArrays],
     sitename = "BlockArrays.jl",
-    strict = VERSION.major == 1 && sizeof(Int) == 8, # only strict mode on 1.0 and Int64
     pages = Any[
         "Home" => "index.md",
         "Manual" => [

src/abstractblockarray.jl

@@ -79,7 +79,7 @@ Throw a `BlockBoundsError` if the specified block indexes are not in bounds for
 Subtypes of `AbstractBlockArray` should
 specialize this method if they need to provide custom block bounds checking behaviors.
 
-```jldoctest; setup = quote using BlockArrays end
+```jldoctest
 julia> A = BlockArray(rand(2,3), [1,1], [2,1]);
 
 julia> blockcheckbounds(A, 3, 2)
@@ -145,7 +145,7 @@ end
 Create a generator that iterates over each block of an `AbstractBlockArray`
 returning views.
 
-```jldoctest; setup = quote using BlockArrays end
+```jldoctest
 julia> v = Array(reshape(1:6, (2, 3)))
 2×3 Matrix{Int64}:
  1  3  5

src/blockarray.jl

@@ -14,7 +14,7 @@ array-constructor-caller would like an uninitialized block array. See also
 undef_blocks (@ref), an alias for UndefBlocksInitializer().
 
 # Examples
-```jldoctest; setup=:(using BlockArrays)
+```jldoctest
 julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2])
 2×2-blocked 3×5 BlockMatrix{Float32}:
  #undef  #undef  #undef  │  #undef  #undef
@@ -33,7 +33,7 @@ type UndefBlocksInitializer (@ref), used in block array initialization to indica
 array-constructor-caller would like an uninitialized block array.
 
 # Examples
-```jldoctest; setup=:(using BlockArrays)
+```jldoctest
 julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2])
 2×2-blocked 3×5 BlockMatrix{Float32}:
  #undef  #undef  #undef  │  #undef  #undef
@@ -99,7 +99,7 @@ end
 """
 Constructs a `BlockArray` with uninitialized blocks from a block type `R` with sizes defined by `block_sizes`.
 
-```jldoctest; setup = quote using BlockArrays end
+```jldoctest
 julia> BlockArray(undef_blocks, Matrix{Float64}, [1,3], [2,2])
 2×2-blocked 4×4 BlockMatrix{Float64}:
  #undef  #undef  │  #undef  #undef
@@ -218,7 +218,7 @@ Construct a `BlockArray` from `blocks`.  `block_sizes` is computed from
 This is an "inverse" of [`blocks`](@ref).
 
 # Examples
-```jldoctest; setup = quote using BlockArrays end
+```jldoctest
 julia> arrays = permutedims(reshape([
                   fill(1.0, 1, 3), fill(2.0, 1, 2),
                   fill(3.0, 2, 3), fill(4.0, 2, 2),

src/blockaxis.jl

@@ -31,7 +31,9 @@ is an `AbstractUnitRange{Int}` that has been divided
 into blocks, and is used to represent axes of block arrays.
 Construction is typically via `blockedrange` which converts
 a vector of block lengths to a `BlockedUnitRange`.
-```jldoctest; setup = quote using BlockArrays end
+
+# Examples
+```jldoctest
 julia> blockedrange([2,2,3])
 3-blocked 7-element BlockedUnitRange{Vector{Int64}}:
  1
@@ -72,14 +74,38 @@ length(a::BlockedUnitRange) = isempty(a.lasts) ? 0 : Integer(last(a.lasts)-a.fir
 """
    blockisequal(a::AbstractUnitRange{Int}, b::AbstractUnitRange{Int})
 
-returns true if a and b have the same block structure.
+Check if `a` and `b` have the same block structure.
+
+# Examples
+```jldoctest
+julia> b1 = blockedrange(1:2)
+2-blocked 3-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
+ 1
+ ─
+ 2
+ 3
+
+julia> b2 = blockedrange([1,1,1])
+3-blocked 3-element BlockedUnitRange{Vector{Int64}}:
+ 1
+ ─
+ 2
+ ─
+ 3
+
+julia> blockisequal(b1, b1)
+true
+
+julia> blockisequal(b1, b2)
+false
+```
 """
 blockisequal(a::AbstractUnitRange{Int}, b::AbstractUnitRange{Int}) = first(a) == first(b) && blocklasts(a) == blocklasts(b)
 blockisequal(a, b, c, d...) = blockisequal(a,b) && blockisequal(b,c,d...)
 """
    blockisequal(a::Tuple, b::Tuple)
 
-returns true if `all(blockisequal.(a,b))`` is true.
+Return `all(blockisequal.(a,b))``
 """
 blockisequal(a::Tuple, b::Tuple) = all(blockisequal.(a, b))
 
@@ -101,18 +127,28 @@ Base.promote_rule(::Type{BlockedUnitRange{CS}}, ::Type{Base.OneTo{Int}}) where C
     blockaxes(A)
 
 Return the tuple of valid block indices for array `A`.
-```jldoctest; setup = quote using BlockArrays end
+
+# Examples
+```jldoctest
 julia> A = BlockArray([1,2,3],[2,1])
 2-blocked 3-element BlockVector{Int64}:
  1
  2
  ─
  3
 
-julia> blockaxes(A)[1]
-2-element BlockRange{1, Tuple{Base.OneTo{Int64}}}:
- Block(1)
- Block(2)
+julia> blockaxes(A)
+(BlockRange(Base.OneTo(2)),)
+
+julia> B = BlockArray(zeros(3,4), [1,2], [1,2,1])
+2×3-blocked 3×4 BlockMatrix{Float64}:
+ 0.0  │  0.0  0.0  │  0.0
+ ─────┼────────────┼─────
+ 0.0  │  0.0  0.0  │  0.0
+ 0.0  │  0.0  0.0  │  0.0
+
+julia> blockaxes(B)
+(BlockRange(Base.OneTo(2)), BlockRange(Base.OneTo(3)))
 ```
 """
 blockaxes(b::BlockedUnitRange) = _blockaxes(b.lasts)
@@ -124,7 +160,9 @@ blockaxes(b) = blockaxes.(axes(b), 1)
     blockaxes(A, d)
 
 Return the valid range of block indices for array `A` along dimension `d`.
-```jldoctest; setup = quote using BlockArrays end
+
+# Examples
+```jldoctest
 julia> A = BlockArray([1,2,3],[2,1])
 2-blocked 3-element BlockVector{Int64}:
  1
@@ -148,7 +186,9 @@ end
 
 Return the tuple of the number of blocks along each
 dimension. See also size and blocksizes.
-```jldoctest; setup = quote using BlockArrays end
+
+# Examples
+```jldoctest
 julia> A = BlockArray(ones(3,3),[2,1],[1,1,1])
 2×3-blocked 3×3 BlockMatrix{Float64}:
  1.0  │  1.0  │  1.0
@@ -173,7 +213,9 @@ blocksize(A,i) = length(blockaxes(A,i))
 
 Return the tuple of the sizes of blocks along each
 dimension. See also size and blocksize.
-```jldoctest; setup = quote using BlockArrays end
+
+# Examples
+```jldoctest
 julia> A = BlockArray(ones(3,3),[2,1],[1,1,1])
 2×3-blocked 3×3 BlockMatrix{Float64}:
  1.0  │  1.0  │  1.0
@@ -282,19 +324,79 @@ end
 """
    blockfirsts(a::AbstractUnitRange{Int})
 
-returns the first index of each block of `a`.
+Return the first index of each block of `a`.
+
+# Examples
+```jldoctest
+julia> b = blockedrange(1:3)
+3-blocked 6-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
+ 1
+ ─
+ 2
+ 3
+ ─
+ 4
+ 5
+ 6
+
+julia> blockfirsts(b)
+3-element Vector{Int64}:
+ 1
+ 2
+ 4
+```
 """
 blockfirsts(a::AbstractUnitRange{Int}) = Ones{Int}(1)
 """
    blocklasts(a::AbstractUnitRange{Int})
 
-returns the last index of each block of `a`.
+Return the last index of each block of `a`.
+
+# Examples
+```jldoctest
+julia> b = blockedrange(1:3)
+3-blocked 6-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
+ 1
+ ─
+ 2
+ 3
+ ─
+ 4
+ 5
+ 6
+
+julia> blocklasts(b)
+3-element ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}:
+ 1
+ 3
+ 6
+```
 """
 blocklasts(a::AbstractUnitRange{Int}) = Fill(length(a),1)
 """
    blocklengths(a::AbstractUnitRange{Int})
 
-returns the length of each block of `a`.
+Return the length of each block of `a`.
+
+# Examples
+```jldoctest
+julia> b = blockedrange(1:3)
+3-blocked 6-element BlockedUnitRange{ArrayLayouts.RangeCumsum{Int64, UnitRange{Int64}}}:
+ 1
+ ─
+ 2
+ 3
+ ─
+ 4
+ 5
+ 6
+
+julia> blocklengths(b)
+3-element Vector{Int64}:
+ 1
+ 2
+ 3
+```
 """
 blocklengths(a::AbstractUnitRange) = blocklasts(a) .- blockfirsts(a) .+ 1
 

src/blockindices.jl

@@ -5,7 +5,7 @@ A `Block` is simply a wrapper around a set of indices or enums so that it can be
 indexing a `AbstractBlockArray` with a `Block` the a block at that block index will be returned instead of
 a single element.
 
-```jldoctest; setup = quote using BlockArrays end
+```jldoctest
 julia> A = BlockArray(ones(2,3), [1, 1], [2, 1])
 2×2-blocked 2×3 BlockMatrix{Float64}:
  1.0  1.0  │  1.0
@@ -120,7 +120,7 @@ and the offset index into the block.
 
 It can be used to index into `BlockArrays` in the following manner:
 
-```jldoctest; setup = quote using BlockArrays end
+```jldoctest
 julia> arr = Array(reshape(1:25, (5,5)));
 
 julia> a = PseudoBlockArray(arr, [3,2], [1,4])

src/blocklinalg.jl

@@ -2,7 +2,22 @@ blockrowsupport(_, A, k) = blockaxes(A,2)
 """
     blockrowsupport(A, k)
 
-gives an iterator containing the possible non-zero blocks in the k-th block-row of A.
+Return an iterator containing the possible non-zero blocks in the k-th block-row of A.
+
+# Examples
+```jldoctest
+julia> B = BlockArray(collect(reshape(1:9, 3, 3)), [1,2], [1,2])
+2×2-blocked 3×3 BlockMatrix{Int64}:
+ 1  │  4  7
+ ───┼──────
+ 2  │  5  8
+ 3  │  6  9
+
+julia> BlockArrays.blockrowsupport(B, 2)
+2-element BlockRange{1, Tuple{Base.OneTo{Int64}}}:
+ Block(1)
+ Block(2)
+```
 """
 blockrowsupport(A, k) = blockrowsupport(MemoryLayout(A), A, k)
 blockrowsupport(A) = blockrowsupport(A, blockaxes(A,1))
@@ -12,7 +27,22 @@ blockcolsupport(_, A, j) = Block.(colsupport(blocks(A), Int.(j)))
 """
     blockcolsupport(A, j)
 
-gives an iterator containing the possible non-zero blocks in the j-th block-column of A.
+Return an iterator containing the possible non-zero blocks in the j-th block-column of A.
+
+# Examples
+```jldoctest
+julia> B = BlockArray(collect(reshape(1:9, 3, 3)), [1,2], [1,2])
+2×2-blocked 3×3 BlockMatrix{Int64}:
+ 1  │  4  7
+ ───┼──────
+ 2  │  5  8
+ 3  │  6  9
+
+julia> BlockArrays.blockcolsupport(B, 2)
+2-element BlockRange{1, Tuple{Base.OneTo{Int64}}}:
+ Block(1)
+ Block(2)
+```
 """
 blockcolsupport(A, j) = blockcolsupport(MemoryLayout(A), A, j)
 blockcolsupport(A) = blockcolsupport(A, blockaxes(A,2))