added docstrings, updated readme

Author: zsunberg

README.md

@@ -91,37 +91,47 @@ julia> length(s)
 ```
 
 ```julia
-julia> s = ArraySpace(UInt8, 2,3)
+julia> s = ArraySpace(1:5, 2,3)
+CommonRLSpaces.RepeatedSpace{UnitRange{Int64}, Tuple{Int64, Int64}}(1:5, (2, 3))
 
 julia> rand(s)
-2×3 Matrix{UInt8}:
- 0x7b  0x38  0xf3
- 0x6a  0xe1  0x28
+2×3 Matrix{Int64}:
+ 4  1  1
+ 3  2  2
 
 julia> rand(s) in s
 true
 
 julia> SpaceStyle(s)
-FiniteSpaceStyle{(2, 3)}()
+FiniteSpaceStyle()
 
 julia> elsize(s)
 (2, 3)
 ```
 
 ```julia
 julia> s = product(-1..1, 0..1)
+Box{StaticArraysCore.SVector{2, Float64}}([-1.0, 0.0], [1.0, 1.0])
 
 julia> rand(s)
-2-element SVector{2, Float64} with indices SOneTo(2):
- 0.5563101538643473
- 0.9227368869418011
+2-element StaticArraysCore.SVector{2, Float64} with indices SOneTo(2):
+ 0.03049072910834738
+ 0.6295234114874269
 
 julia> rand(s) in s
 true
 
 julia> SpaceStyle(s)
-ContinuousSpaceStyle{(2,)}()
+ContinuousSpaceStyle()
 
 julia> elsize(s)
 (2,)
+
+julia> bounds(s)
+([-1.0, 0.0], [1.0, 1.0])
+
+julia> clamp([5, 5], s)
+2-element StaticArraysCore.SizedVector{2, Float64, Vector{Float64}} with indices SOneTo(2):
+ 1.0
+ 1.0
 ```

src/CommonRLSpaces.jl

@@ -6,6 +6,8 @@ using Reexport
 
 using StaticArrays
 using FillArrays
+using Random
+import Base: clamp
 
 export
     SpaceStyle,

src/array.jl

@@ -57,6 +57,11 @@ struct RepeatedSpace{B, S<:Tuple} <: AbstractArraySpace
     elsize::S
 end
 
+"""
+    ArraySpace(base_space, size...)
+
+Create a space of Arrays with shape `size`, where each element of the array is drawn from `base_space`.
+"""
 ArraySpace(base_space, size...) = RepeatedSpace(base_space, size)
 
 SpaceStyle(s::RepeatedSpace) = SpaceStyle(s.base_space)

src/basic.jl

@@ -1,13 +1,14 @@
-using Random
-
-#####
-
 abstract type AbstractSpaceStyle end
 
 struct FiniteSpaceStyle <: AbstractSpaceStyle end
 struct ContinuousSpaceStyle <: AbstractSpaceStyle end
 struct UnknownSpaceStyle <: AbstractSpaceStyle end
 
+"""
+    SpaceStyle(space)
+
+Holy-style trait that describes whether the space is continuous, finite discrete, or an unknown type. See CommonRLInterface for a more detailed description of the styles.
+"""
 SpaceStyle(space::Any) = UnknownSpaceStyle()
 
 SpaceStyle(::Tuple) = FiniteSpaceStyle()
@@ -30,9 +31,34 @@ promote_spacestyle(_, _) = UnknownSpaceStyle()
 # handle case of 3 or more
 promote_spacestyle(s1, s2, s3, others...) = foldl(promote_spacestyle, (s1, s2, s3, args...))
 
+"Return the size of the objects in a space. This is guaranteed to be defined if the objects in the space are arrays, but otherwise it may not be defined."
 function elsize end # note: different than Base.elsize
 
+"""
+    bounds(space)
+
+Return a `Tuple` containing lower and upper bounds for the elements in a space.
+
+For example, if `space` is a unit circle, `bounds(space)` will return `([-1.0, -1.0], [1.0, 1.0])`. This allows agents to choose policies that appropriately cover the space e.g. a normal distribution with a mean of `mean(bounds(space))` and a standard deviation of half the distance between the bounds.
+
+`bounds` should be defined for ContinuousSpaceStyle spaces.
+
+# Example
+```juliadoctest
+julia> bounds(1..2)
+(1, 2)
+```
+"""
 function bounds end
 
+"""
+    clamp(x, space)
+
+Return an element of `space` that is near `x`.
+
+For example, if `space` is a unit circle, `clamp([2.0, 0.0], space)` might return `[1.0, 0.0]`. This allows for a convenient way for an agent to find a valid action if they sample actions from a distribution that doesn't match the space exactly (e.g. a normal distribution).
+"""
+function clamp end
+
 bounds(i::AbstractInterval) = (infimum(i), supremum(i))
 Base.clamp(x, i::AbstractInterval) = IntevalSets.clamp(x, i)

src/product.jl

@@ -18,8 +18,16 @@ struct TupleProduct{T<:Tuple}
     ss::T
 end
 
+"""
+    TupleProduct(space1, space2, ...)
+
+Create a space representing the Cartesian product of the argument. Each element is a `Tuple` containing one element from each of the constituent spaces.
+
+Use `subspaces` to access a `Tuple` containing the constituent spaces.
+"""
 TupleProduct(s1, s2, others...) = TupleProduct((s1, s2, others...))
 
+"Return a `Tuple` containing the spaces used to create a `TupleProduct`"
 subspaces(s::TupleProduct) = s.ss
 
 product(s1::TupleProduct, s2::TupleProduct) = TupleProduct(subspaces(s1)..., subspaces(s2)...)