Add missing documentation

docs/src/lib/concrete_binary_operations/convex_hull.md

@@ -10,6 +10,7 @@ CurrentModule = LazySets
 # Convex Hull
 
 ```@docs
-convex_hull(::Vector{VN}) where {N, VN<:AbstractVector{N}}
+convex_hull(::Vector{<:AbstractVector})
+convex_hull!(::Vector{<:AbstractVector})
 monotone_chain!
 ```

docs/src/lib/interfaces/overview.md

@@ -1,5 +1,13 @@
 # Overview
 
+```@meta
+CurrentModule = LazySets
+```
+
+```@docs
+LazySets
+```
+
 This section of the manual describes the interfaces for different set types.
 Every set that fits the description of an interface should also implement it.
 This helps in several ways:

docs/src/lib/lazy_operations/CartesianProduct.md

@@ -38,6 +38,7 @@ Inherited from [`LazySet`](@ref):
 
 ```@docs
 CartesianProductArray
+CartesianProduct!
 ×(::LazySet, ::LazySet...)
 *(::LazySet, ::LazySet...)
 dim(::CartesianProductArray)

docs/src/lib/lazy_operations/ConvexHull.md

@@ -30,6 +30,7 @@ Inherited from [`LazySet`](@ref):
 ```@docs
 ConvexHullArray
 CHArray
+ConvexHull!
 dim(::ConvexHullArray)
 ρ(::AbstractVector, ::ConvexHullArray)
 σ(::AbstractVector, ::ConvexHullArray)

docs/src/lib/lazy_operations/ExponentialMap.md

@@ -34,6 +34,9 @@ Inherited from [`AbstractAffineMap`](@ref):
 SparseMatrixExp
 *(::SparseMatrixExp, ::LazySet)
 get_row(::SparseMatrixExp, ::Int)
+get_rows(::SparseMatrixExp, ::AbstractArray{Int})
+get_column(::SparseMatrixExp, ::Int)
+get_columns(::SparseMatrixExp, ::AbstractArray{Int})
 ```
 
 ## [Exponential projection map (ExponentialProjectionMap)](@id def_ExponentialProjectionMap)

docs/src/lib/lazy_operations/Intersection.md

@@ -49,6 +49,7 @@ IntersectionCache
 
 ```@docs
 IntersectionArray
+Intersection!
 ∩(::LazySet, ::LazySet...)
 dim(::IntersectionArray)
 σ(::AbstractVector, ::IntersectionArray)

docs/src/lib/lazy_operations/MinkowskiSum.md

@@ -33,6 +33,7 @@ Inherited from [`LazySet`](@ref):
 
 ```@docs
 MinkowskiSumArray
+MinkowskiSum!
 ⊕(::LazySet, ::LazySet...)
 +(::LazySet, ::LazySet...)
 dim(::MinkowskiSumArray)

docs/src/lib/lazy_operations/UnionSet.md

@@ -24,6 +24,7 @@ vertices_list(::UnionSet)
 
 ```@docs
 UnionSetArray
+UnionSet!
 dim(::UnionSetArray)
 array(::UnionSetArray)
 σ(::AbstractVector, ::UnionSetArray; algorithm="support_vector")

docs/src/lib/utils.md

@@ -4,7 +4,15 @@ CurrentModule = LazySets
 
 # Utilities
 
-## Macros
+## Array set types
+
+```@docs
+flatten
+neutral
+absorbing
+```
+
+### Internal helper macros
 
 ```@docs
 @neutral

src/ConcreteOperations/convex_hull.jl

@@ -66,8 +66,8 @@ function _convex_hull_set(vlist; n::Int=(isempty(vlist) ? -1 : length(vlist[1]))
 end
 
 """
-    convex_hull(points::Vector{VN}; [algorithm]=nothing, [backend]=nothing,
-                [solver]=nothing) where {N, VN<:AbstractVector{N}}
+    convex_hull(points::Vector{<:AbstractVector}; [algorithm]=nothing,
+                [backend]=nothing, [solver]=nothing)
 
 Compute the convex hull of a list of points.
 
@@ -111,7 +111,7 @@ The higher-dimensional case is treated using the concrete polyhedra library
 
 ### Notes
 
-For the in-place version use `convex_hull!` instead of `convex_hull`.
+For the in-place version use [`convex_hull!(::Vector{<:AbstractVector})`](@ref).
 
 ### Examples
 
@@ -126,14 +126,34 @@ julia> typeof(hull)
 Vector{Vector{Float64}} (alias for Array{Array{Float64, 1}, 1})
 ```
 """
-function convex_hull(points::Vector{VN}; algorithm=nothing, backend=nothing,
-                     solver=nothing) where {N,VN<:AbstractVector{N}}
+function convex_hull(points::Vector{<:AbstractVector}; algorithm=nothing,
+                     backend=nothing, solver=nothing)
     return convex_hull!(copy(points); algorithm=algorithm, backend=backend,
                         solver=solver)
 end
 
-function convex_hull!(points::Vector{VN}; algorithm=nothing, backend=nothing,
-                      solver=nothing) where {N,VN<:AbstractVector{N}}
+"""
+    convex_hull!(points::Vector{<:AbstractVector}; [algorithm]=nothing,
+                 [backend]=nothing, [solver]=nothing)
+
+Compute the convex hull of a list of points in-place.
+
+### Input
+
+- `points`    -- list of points (modified in-place)
+- `algorithm` -- (optional, default: `nothing`) the convex-hull algorithm; see
+                 below for valid options
+- `backend`   -- (optional, default: `nothing`) polyhedral computation backend
+                 for higher-dimensional point sets
+- `solver`    -- (optional, default: `nothing`) the linear-programming solver
+                 used in the backend
+
+### Notes
+
+See [`convex_hull(::Vector{<:AbstractVector})`](@ref) for more details.
+"""
+function convex_hull!(points::Vector{<:AbstractVector}; algorithm=nothing,
+                      backend=nothing, solver=nothing)
     m = length(points)
 
     # zero or one point

src/Interfaces/AbstractArraySet.jl

@@ -24,6 +24,25 @@ function Base.iterate(X::AbstractArraySet, state=1)
     return iterate(array(X), state)
 end
 
+"""
+    flatten(X::LazySets.AbstractArraySet)
+
+Flatten an array set, i.e., resolve potential nestings.
+
+### Examples
+
+```jldoctest
+julia> E1 = EmptySet(1); E2 = EmptySet(2); E3 = EmptySet(3);
+
+julia> X = MinkowskiSumArray([E1, MinkowskiSumArray([E2, E2])])
+MinkowskiSumArray{Float64, LazySet{Float64}}(LazySet{Float64}[∅(1), MinkowskiSumArray{Float64, ∅}(∅[∅(2), ∅(2)])])
+
+julia> flatten(X)
+MinkowskiSumArray{Float64, ∅}(∅[∅(1), ∅(2), ∅(2)])
+```
+"""
+function flatten end
+
 function flatten!(arr, X, bin_op)
     if X isa bin_op
         flatten!(arr, first(X), bin_op)

src/LazyOperations/CartesianProductArray.jl

@@ -29,6 +29,14 @@ function CartesianProductArray(n::Int=0, N::Type=Float64)
     return CartesianProductArray(arr)
 end
 
+"""
+    CartesianProduct!(X, Y)
+
+Convenience function to compute the lazy Cartesian product and modify
+`CartesianProductArray`s in-place.
+"""
+function CartesianProduct! end
+
 """
 ```
     *(X::LazySet, Xs::LazySet...)

src/LazyOperations/ConvexHullArray.jl

@@ -30,6 +30,14 @@ struct ConvexHullArray{N,S<:LazySet{N}} <: ConvexSet{N}
     array::Vector{S}
 end
 
+"""
+    ConvexHull!(X, Y)
+
+Convenience function to compute the lazy convex hull and modify
+`ConvexHullArray`s in-place.
+"""
+function ConvexHull! end
+
 isoperationtype(::Type{<:ConvexHullArray}) = true
 
 # constructor for an empty hull with optional size hint and numeric type

src/LazyOperations/ExponentialMap.jl

@@ -86,6 +86,23 @@ function size(spmexp::SparseMatrixExp, ax::Int)
     return size(spmexp.M, ax)
 end
 
+"""
+    get_column(spmexp::SparseMatrixExp{N}, j::Int;
+               [backend]=get_exponential_backend()) where {N}
+
+Compute a single column of a sparse matrix exponential.
+
+### Input
+
+- `spmexp`  -- sparse matrix exponential
+- `j`       -- column index
+- `backend` -- (optional; default: `get_exponential_backend()`) exponentiation
+               backend
+
+### Output
+
+A column vector corresponding to the `j`th column of the matrix exponential.
+"""
 function get_column(spmexp::SparseMatrixExp{N}, j::Int;
                     backend=get_exponential_backend()) where {N}
     n = size(spmexp, 1)
@@ -94,6 +111,23 @@ function get_column(spmexp::SparseMatrixExp{N}, j::Int;
     return _expmv(backend, one(N), spmexp.M, aux)
 end
 
+"""
+    get_columns(spmexp::SparseMatrixExp{N}, J::AbstractArray;
+               [backend]=get_exponential_backend()) where {N}
+
+Compute multiple columns of a sparse matrix exponential.
+
+### Input
+
+- `spmexp`  -- sparse matrix exponential
+- `J`       -- list of column indices
+- `backend` -- (optional; default: `get_exponential_backend()`) exponentiation
+               backend
+
+### Output
+
+A matrix with one column vector for each entry in `J`.
+"""
 function get_columns(spmexp::SparseMatrixExp{N}, J::AbstractArray;
                      backend=get_exponential_backend()) where {N}
     n = size(spmexp, 1)
@@ -111,7 +145,7 @@ end
     get_row(spmexp::SparseMatrixExp{N}, i::Int;
             [backend]=get_exponential_backend()) where {N}
 
-Return a single row of a sparse matrix exponential.
+Compute a single row of a sparse matrix exponential.
 
 ### Input
 
@@ -138,6 +172,23 @@ function get_row(spmexp::SparseMatrixExp{N}, i::Int;
     return transpose(_expmv(backend, one(N), transpose(spmexp.M), aux))
 end
 
+"""
+    get_rows(spmexp::SparseMatrixExp{N}, I::AbstractArray;
+               [backend]=get_exponential_backend()) where {N}
+
+Compute multiple rows of a sparse matrix exponential.
+
+### Input
+
+- `spmexp`  -- sparse matrix exponential
+- `I`       -- list of row indices
+- `backend` -- (optional; default: `get_exponential_backend()`) exponentiation
+               backend
+
+### Output
+
+A transposed matrix with one (transposed) column vector for each entry in `I`.
+"""
 function get_rows(spmexp::SparseMatrixExp{N}, I::AbstractArray{Int};
                   backend=get_exponential_backend()) where {N}
     n = size(spmexp, 1)

src/LazyOperations/IntersectionArray.jl

@@ -23,6 +23,14 @@ struct IntersectionArray{N,S<:LazySet{N}} <: LazySet{N}
     array::Vector{S}
 end
 
+"""
+    Intersection!(X, Y)
+
+Convenience function to compute the lazy intersection and modify
+`IntersectionArray`s in-place.
+"""
+function Intersection! end
+
 """
     ∩(X::LazySet, Xs::LazySet...)
     ∩(Xs::Vector{<:LazySet})

src/LazyOperations/MinkowskiSumArray.jl

@@ -24,6 +24,14 @@ struct MinkowskiSumArray{N,S<:LazySet{N}} <: LazySet{N}
     array::Vector{S}
 end
 
+"""
+    MinkowskiSum!(X, Y)
+
+Convenience function to compute the lazy Minkowski sum and modify
+`MinkowskiSumArray`s in-place.
+"""
+function MinkowskiSum! end
+
 """
     +(X::LazySet, Xs::LazySet...)
     +(Xs::Vector{<:LazySet})

src/LazyOperations/UnionSetArray.jl

@@ -18,6 +18,14 @@ struct UnionSetArray{N,S<:LazySet{N}} <: LazySet{N}
     array::Vector{S}
 end
 
+"""
+    UnionSet!(X, Y)
+
+Convenience function to compute the lazy union and modify `UnionSetArray`s
+in-place.
+"""
+function UnionSet! end
+
 isoperationtype(::Type{<:UnionSetArray}) = true
 isconvextype(::Type{<:UnionSetArray}) = false
 

src/LazySets.jl

@@ -1,3 +1,8 @@
+"""
+    LazySets
+
+Scalable symbolic-numeric set computations in Julia.
+"""
 module LazySets
 
 using Reexport

src/Utils/macros.jl

@@ -1,3 +1,10 @@
+"""
+    neutral(T::Type{<:LazySet})
+
+Get the neutral set type for a lazy binary operation, if any.
+"""
+function neutral end
+
 """
     @neutral(SET, NEUT)
 
@@ -68,6 +75,13 @@ macro neutral(SET, NEUT)
     return nothing
 end
 
+"""
+    absorbing(T::Type{<:LazySet})
+
+Get the absorbing set type for a lazy binary operation, if any.
+"""
+function absorbing end
+
 """
     @absorbing(SET, ABS)