📝 type docs

docs/src/index.md

@@ -8,3 +8,8 @@ data.
 
 !!! warning "This package is in development"
     The `BiodiversityObservationNetworks.jl` package is currently under development. The API is not expected to change a lot, but it may change in order to facilitate the integration of new features.
+
+```@autodocs
+Modules = [BiodiversityObservationNetworks]
+Order   = [:type, :function]
+```

src/geometry/bon.jl

@@ -1,24 +1,48 @@
 const __COORDINATE_TYPES = Union{Tuple{<:Real, <:Real}, CartesianIndex}
 
-# TODO: extent this to be GeoInterface.PointLike compat
+"""
+    Node
+
+A single sampling location within a [`BiodiversityObservationNetwork`](@ref), represented as a coordinate.
+
+A `Node` extends the GeoInterface PointTrait type.
+"""
 struct Node{C <: __COORDINATE_TYPES}
     coordinate::C
 end
 Base.show(io::IO, node::Node) = print(io, "Node at $(node.coordinate)")
 Base.getindex(node::Node, i) = getindex(node.coordinate, i)
 
+GI.isgeometry(::Node)::Bool = true
+GI.geomtrait(::Node)::DataType = PointTrait()
+GI.ncoord(::PointTrait, ::Node)::Integer = 1
+GI.getcoord(::PointTrait, node::Node, i)::Real = node[i]
 
 is_bonifyable(::T) where T = T <: Union{<:__COORDINATE_TYPES,Vector{<:__COORDINATE_TYPES}}
 
 
+"""
+    BiodiversityObservationNetwork
+
+A set of [`Node`](@ref)s that together create a sampling design for monitoring
+biodiversity. 
+
+`BiodiversityObservationNetwork` extends the GeoInterface MultiPointTrait type. 
+"""
 struct BiodiversityObservationNetwork{N <: Node}
     nodes::Vector{N}
 end
+
 Base.show(io::IO, bon::BiodiversityObservationNetwork) =
     print(io, "BiodiversityObservationNetwork with $(length(bon)) nodes")
 Base.getindex(bon::BiodiversityObservationNetwork, i::Integer) = bon.nodes[i]
 Base.length(bon::BiodiversityObservationNetwork) = length(bon.nodes)
 Base.iterate(bon::BiodiversityObservationNetwork, i) = iterate(bon.nodes, i)
 Base.iterate(bon::BiodiversityObservationNetwork) = iterate(bon.nodes)
-
 Base.vcat(bons::Vector{<:BiodiversityObservationNetwork}) = BiodiversityObservationNetwork(vcat([b.nodes for b in bons]...))
+
+
+GI.isgeometry(::BiodiversityObservationNetwork)::Bool = true
+GI.geomtrait(::BiodiversityObservationNetwork)::DataType = MultiPointTrait()
+GI.ngeom(::MultiPointTrait, bon::BiodiversityObservationNetwork)::Integer = length(bon)
+GI.getgeom(::MultiPointTrait, bon::BiodiversityObservationNetwork, i) = bon[i]

src/geometry/polygon.jl

@@ -1,3 +1,9 @@
+"""
+    Polygon
+
+A Polygon extends the GeoInterface API for both PolygonTrait and
+MultiPolygonTraits. 
+"""
 struct Polygon{T, G}
     geometry::G
     function Polygon(::T, geom::G) where {T <: GI.AbstractTrait, G}

src/geometry/raster.jl

@@ -1,5 +1,15 @@
 const __RASTER_TYPES = Union{SDMLayer, Matrix{<:Real}}
 
+"""
+    Raster
+
+A `Raster` stores gridded data. The internal representation of this data can be
+an SDMLayer (from
+[SimpleSDMLayers.jl](https://github.com/PoisotLab/SpeciesDistributionToolkit.jl))
+or a Matrix.
+
+`Raster` extends the RasterTrait type from GeoInterface.
+"""
 struct Raster{R <: __RASTER_TYPES}
     raster::R
 end
@@ -29,18 +39,16 @@ _get_raster_crs(raster::Raster{<:SDMLayer}) = GI.crs(raster.raster)
 _get_raster_crs(::Raster{<:Matrix}) = nothing
 
 
+# SpeciesDistributionToolkit Overloads
 SDT.eastings(r::Raster{<:Matrix}) = 0:(1/size(r)[2]):1
 SDT.northings(r::Raster{<:Matrix}) = 0:(1/size(r)[1]):1
-
 SDT.eastings(r::Raster{<:SDMLayer}) = eastings(r.raster)
 SDT.northings(r::Raster{<:SDMLayer}) = northings(r.raster)
 
-
+# GeoInterface overloads
 GI.isgeometry(::Raster)::Bool = true
 GI.geomtrait(::Raster)::DataType = GI.RasterTrait()
 GI.israster(::Raster)::Bool = true
 GI.trait(::Raster) = RasterTrait()
-
-
 GI.extent(::RasterTrait, raster::Raster)::GI.Extents.Extent = _get_raster_extent(raster)
 GI.crs(::RasterTrait, raster::Raster)::GeoFormatTypes.CoordinateReferenceSystem = _get_raster_crs(raster)

src/geometry/stack.jl

@@ -1,3 +1,9 @@
+"""
+    RasterStack
+
+A `RasterStack` is a set of [`Raster`](@ref)s, which all have the same
+resolution and extent, for storing multiple raster-like environmental variables 
+"""
 struct RasterStack{R<:Raster}
     stack::Vector{R}
 end

src/sample.jl

@@ -1,3 +1,9 @@
+"""
+    BONSampler
+
+An abstract type that is the supertype for all methods for sampling
+BiodiversityObservationNetworks. 
+"""
 abstract type BONSampler end 
 
 function _what_did_you_pass(geom)

src/samplers/grid.jl

@@ -1,16 +1,25 @@
+"""
+    Grid
+
+`Grid` is a type of [`BONSampler`](@ref) for generating
+[`BiodiversityObservationNetwork`](@ref)s with [`Node`](@ref)s  structured as a
+systematic grid over the study area.
+
+*Arguments*:
+- `longitude_spacing`
+- `latitude_spacing`
+"""
 Base.@kwdef struct Grid{F<:Real} <: BONSampler
     longitude_spacing::F = 1. # in wgs84 coordinates
     latitude_spacing::F  = 1.
 end 
 
-
 function _generate_grid(sampler::Grid, domain) 
     x, y = GeoInterface.extent(domain)
     x_step, y_step = sampler.longitude_spacing, sampler.latitude_spacing
     BiodiversityObservationNetwork([Node((i,j)) for i in x[1]:x_step:x[2], j in y[1]:y_step:y[2] if GeometryOps.contains(domain, (i,j))])
 end 
 
-
 function _sample(sampler::Grid, domain::T) where T 
     if GeoInterface.isgeometry(domain)
         return _generate_grid(sampler, domain)

src/samplers/kmeans.jl

@@ -1,8 +1,18 @@
+""" 
+    KMeans
+
+`KMeans` is a [`BONSampler`](@ref) that generates
+[`BiodiversityObservationNetwork`](@ref)s that aim to be representative of the
+distribution of environmental variables across an extent represented as a
+[`RasterStack`](@ref).
+
+*Arguments*:
+- `k`: the number of sampling sites
+"""
 struct KMeans{I<:Integer} <: BONSampler
     k::I
 end 
 
-
 function _sample(::KMeans, ::T) where T 
     @error "Can't use KMeans on a $T"
 end 

src/samplers/simplerandom.jl

@@ -1,3 +1,10 @@
+"""
+    SimpleRandom
+
+`SimpleRandom` is a [`BONSampler`](@ref) for sampling
+[`BiodiversityObservationNetwork`](@ref)s where each location in the spatial
+extent has the same probability of inclusion. 
+"""
 struct SimpleRandom{I<:Integer} <: BONSampler
     number_of_nodes::I
 end

src/samplers/spatiallystratified.jl

@@ -1,3 +1,8 @@
+"""
+    SpatiallyStratified
+
+`SpatiallyStratified` is a [`BONSampler`](@ref) for choosing sites across a set of different spatial stratum. 
+"""
 struct SpatiallyStratified{I<:Integer} <: BONSampler
     number_of_nodes::I
 end