document transformation keywords

src/primitives.jl

@@ -1,18 +1,31 @@
+const THREADED_KEYWORD = "- `threaded`: `true` or `false`. Whether to use multithreading. Defaults to `false`."
+const CRS_KEYWORD = "- `crs`: The CRS to attach to geometries. Defaults to `nothing`."
+const CALC_EXTENT_KEYWORD = "- `calc_extent`: `true` or `false`. Whether to calculate the extent. Defaults to `false`."
+
+const APPLY_KEYWORDS = """
+$THREADED_KEYWORD
+$CRS_KEYWORD
+$CALC_EXTENT_KEYWORD
+"""
 
 # # Primitive functions
 
 # This file mainly defines the [`apply`](@ref) function.
 
 """
-    apply(f, target::Type{<:AbstractTrait}, obj; crs)
+    apply(f, target::Type{<:AbstractTrait}, obj; kw...)
 
 Reconstruct a geometry or feature using the function `f` on the `target` trait.
 
 `f(target_geom) => x` where `x` also has the `target` trait, or an equivalent.
 
 The result is an functionally similar geometry with values depending on `f`
 
-# Flipped point the order in any feature or geometry, or iterables of either:
+$APPLY_KEYWORDS
+
+# Example
+
+Flipped point the order in any feature or geometry, or iterables of either:
 
 ```juia
 import GeoInterface as GI

src/transformations/extent.jl

@@ -1,29 +1,17 @@
 """
     embed_extent(obj)
 
-Recursively wrap the object with a `GeoInterface.Wrappers` geometry,
+Recursively wrap the object with a GeoInterface.jl geometry,
 calculating and adding an `Extents.Extent` to all objects.
 
-This can improve performance when extents need to be checked multiple times.
-"""
-embed_extent(x; kw...) = apply(extent_applicator, GI.AbstractTrait, x; kw...)
+This can improve performance when extents need to be checked multiple times,
+such when needing to check if many points are in geometries, and using their extents
+as a quick filter for obviously exterior points.
+
+# Keywords
 
-# We recursively run `embed_extent` so the lowest level
-# extent is calculated first and bubbles back up.
-# This means we touch each point only once.
-extent_applicator(x) = extent_applicator(trait(x), x)
-extent_applicator(::Nothing, xs::AbstractArray) = embed_extent.(xs)
-function extent_applicator(trait::GI.AbstractGeometryTrait, geom)
-    children_with_extents = map(GI.getgeom(geom)) do g
-        embed_extent(g)
-    end
-    wrapper_type = GI.geointerface_geomtype(trait)
-    extent = GI.extent(wrapper_type(children_with_extents))
-    return wrapper_type(children_with_extents; extent, crs=GI.crs(geom))
-end
-function extent_applicator(trait::Union{GI.AbstractCurveTrait,GI.MultiPointTrait}, geom)
-    wrapper_type = GI.geointerface_geomtype(trait)
-    extent = GI.extent(geom)
-    return wrapper_type(geom; extent, crs=GI.crs(geom))
-end
-extent_applicator(::GI.PointTrait, point) = point
+$THREADED_KEYWORD
+$CRS_KEYWORD
+"""
+embed_extent(x; threaded=false, crs=nothing) = 
+    apply(identity, GI.PointTrait, x; calc_extent=true, threaded, crs)

src/transformations/flip.jl

@@ -9,6 +9,10 @@
 Swap all of the x and y coordinates in obj, otherwise
 keeping the original structure (but not necessarily the
 original type).
+
+## Keywords 
+
+$APPLY_KEYWORDS
 """
 function flip(geom; kw...) 
     if _is3d(geom)

src/transformations/reproject.jl

@@ -33,6 +33,7 @@ needed if it is not retreivable from the geometry with `GeoInterface.crs(geometr
 -`always_xy`: force x, y coordinate order, `true` by default.
     `false` will expect and return points in the crs coordinate order.
 -`time`: the time for the coordinates. `Inf` by default.
+$APPLY_KEYWORDS
 """
 function reproject(geom;
     source_crs=nothing, target_crs=nothing, transform=nothing, kw...

src/transformations/simplify.jl

@@ -22,6 +22,7 @@ abstract type SimplifyAlg end
 
 const SIMPLIFY_ALG_KEYWORDS = """
 ## Keywords
+
 - `ratio`: the fraction of points that should remain after `simplify`. 
     Useful as it will generalise for large collections of objects.
 - `number`: the number of points that should remain after `simplify`.
@@ -48,7 +49,7 @@ end
 
 """
     simplify(obj; kw...)
-    simplify(::SimplifyAlg, obj)
+    simplify(::SimplifyAlg, obj; kw...)
 
 Simplify a geometry, feature, feature collection, 
 or nested vectors or a table of these.
@@ -62,6 +63,14 @@ listed in order of increasing quality but decreaseing performance.
 The default behaviour is `simplify(DouglasPeucker(; kw...), obj)`.
 Pass in other [`SimplifyAlg`](@ref) to use other algorithms.
 
+# Keywords
+
+$APPLY_KEYWORDS
+
+Keywords for DouglasPeucker are allowed when no algorithm is specified:
+
+$SIMPLIFY_ALG_KEYWORDS
+
 # Example
 
 Simplify a polygon to have six points:
@@ -99,8 +108,8 @@ GI.npoint(simple)
 6
 ```
 """
-simplify(data; calc_extent=false, threaded=false, kw...) =
-    _simplify(DouglasPeucker(; kw...), data; calc_extent, threaded)
+simplify(data; calc_extent=false, threaded=false, crs=nothing, kw...) =
+    _simplify(DouglasPeucker(; kw...), data; calc_extent, threaded, crs)
 simplify(alg::SimplifyAlg, data; kw...) = _simplify(alg, data; kw...)
 
 function _simplify(alg::SimplifyAlg, data; kw...)

src/transformations/tuples.jl

@@ -3,7 +3,14 @@
 """
     tuples(obj)
 
-Convert all points on obj to `Tuple`s.
+Convert all points in `obj` to `Tuple`s, wherever the are nested.
+
+Returns a similar object or collection of objects using GeoInterface.jl
+geometries wrapping `Tuple` points.
+
+# Keywords
+
+$APPLY_KEYWORDS
 """
 function tuples(geom; kw...) 
     if _is3d(geom)