Added doctests. Expanded the documentation.

Author: evetion

Project.toml

@@ -5,14 +5,13 @@ version = "1.0.0"
 
 [deps]
 Extents = "411431e0-e8b7-467b-b5e0-f676ba4f2910"
-RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 
 [compat]
-RecipesBase = "1"
 julia = "1"
 
 [extras]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Test", "Documenter"]

docs/make.jl

@@ -18,6 +18,7 @@ makedocs(;
         "Home" => "index.md",
         "Background" => Any[
             "Simple Features"=>"background/sf.md",
+            "History"=>"background/history.md",
         ],
         "Tutorials" => Any[
             "Installation"=>"tutorials/installation.md",
@@ -31,7 +32,8 @@ makedocs(;
             "API" => "reference/api.md"
             "Implementations" => "reference/integrations.md"
         ],
-    ]
+    ],
+    doctest=true
 )
 
 deploydocs(;

docs/src/background/history.md

@@ -0,0 +1,21 @@
+# History
+The previous pre-1.0 releases of GeoInterface.jl were smaller in scope, aligned to geointerface in Python [^sgillies]
+which builds on GeoJSON [^geojson]. It provided abstract types and expected other geometries to be implemented as a subtype.
+Recent Julia developments have shown that subtyping is difficult--you can only choose one supertype--and many packages moved to trait-based interfaces. Tables.jl is an excellent example of traits-based interface.
+
+[^sgillies]: https://gist.github.com/sgillies/2217756
+[^geojson]: https://geojson.org/
+
+## Backwards compatibility
+To keep function compatibility with pre-v1 releases--even while switching to traits--we keep the following methods.
+```julia
+# for Features
+isfeature # new
+geometry
+properties
+
+# for Geometries
+coordinates
+```
+
+However, the `position` type is gone and merged with `PointTrait`.

docs/src/background/sf.md

@@ -12,6 +12,7 @@ All types used here come from the SF. We added `Trait` to all geometry types her
 ![SF Type hierarchy. From the Simple Feature standard by OGC.](types.png)
 `The SF Type hierarchy. From OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture at http://www.opengis.net/doc/is/sfa/1.2.1.`
 
+
 ## Changes with respect to SF
 While we try to adhere to SF, there are changes and extensions to make it more Julian.
 
@@ -54,15 +55,6 @@ Not all SF functions are implemented, either as a possibly slower fallback or em
 dimension  # topological dimensions
 spatialDimension
 
-
 locateAlong
 locateBetween
 ```
-
-## History
-The previous pre-1.0 releases of GeoInterface.jl were smaller in scope, aligned to geointerface in Python [^sgillies]
-which builds on GeoJSON [^geojson]. It provided abstract types and expected other geometries to be implemented as a subtype.
-Recent Julia developments have shown that subtyping is difficult--you can only choose one supertype--and many packages moved to trait-based interfaces. Tables.jl is an excellent example.
-
-[^sgillies]: https://gist.github.com/sgillies/2217756
-[^geojson]: https://geojson.org/

docs/src/guides/defaults.md

@@ -28,7 +28,7 @@ nhole(p::AbstractPolygonTrait, geom) = nring(p, geom) - 1
 gethole(p::AbstractPolygonTrait, geom, i) = getring(p, geom, i + 1)
 ```
 ## LineStrings
-Simarly for LineStrings, we have the following
+Similarly for `LineStringTrait`s, we have the following
 ```julia
 startpoint(geom) = getpoint(geom, 1)
 endpoint(geom) = getpoint(geom, length(geom))

docs/src/guides/developer.md

@@ -4,24 +4,30 @@ CurrentModule = GeoInterface
 
 # Implementing GeoInterface
 GeoInterface requires six functions to be defined for a custom geometry. On top of that
-it could be useful to also implement some optional methods if they apply or are faster than the fallbacks.
+it could be useful to also implement some optional methods if they apply or are faster than the [Fallbacks](@ref).
 
 If your package also supports geospatial operations on geometries--such as intersections--, please
 also implement those interfaces where applicable.
 
+Last but not least, we also provide an interface for features--geometries with properties--if applicable.
+
 ## Required for Geometry
 
 ```julia
 GeoInterface.isgeometry(geom::customgeom)::Bool = true
-GeoInterface.geomtype(geom::customgeom)::DataType = GeoInterface.XTraitTrait() # <: AbstractGeometryTrait
+GeoInterface.geomtype(geom::customgeom)::DataType = GeoInterface.XTrait() # <: AbstractGeometryTrait
+# for PointTraits
 GeoInterface.ncoord(geomtype(geom), geom::customgeom)::Integer
-GeoInterface.getcoord(geomtype(geom), geom::customgeom, i)::Real  # only for PointTraits
+GeoInterface.getcoord(geomtype(geom), geom::customgeom, i)::Real
+# for non PointTraits
 GeoInterface.ngeom(geomtype(geom), geom::customgeom)::Integer
-GeoInterface.getgeom(geomtype(geom), geom::customgeom, i)  # geomtype -> GeoInterface.Y
+GeoInterface.getgeom(geomtype(geom), geom::customgeom, i)
 ```
-Where the `getgeom` and `getcoord` could be an iterator (without the `i`) as well. It will return a new geom with the correct `geomtype`. The `ngeom` and `getgeom` are aliases for their geom specific counterparts, such as `npoints` and `getpoint` for LineStrings.
+Where the `getgeom` and `getcoord` could be an iterator (without the `i`) as well. It will return a new geom with the correct `geomtype`.
+This means that a call to `getgeom` on a geometry that has a `LineStringTrait` should return something that implements the `PointTrait`. This hierarchy can be checked programmatically with [`subtrait`](@ref). You read more about the `geomtype` in the [Type hierarchy](@ref).
+
+The `ngeom` and `getgeom` are aliases for their geom specific counterparts, such as `npoints` and `getpoint` for `LineStringTrait`s.
 
-You read more about the `geomtype` in the [Type hierarchy](@ref).
 
 ## Optional for Geometry
 
@@ -71,15 +77,16 @@ union(geomtype(a), geomtype(b), a, b)
 ```
 
 ## Testing the interface
-GeoInterface provides a Testsuite for a geom type to check whether all functions that have been implemented also work as expected.
+GeoInterface provides a Testsuite for a geom type to check whether the required functions that have been correctly implemented and work as expected.
 
 ```julia
 GeoInterface.testgeometry(geom)
+GeoInterface.testfeature(geom)
 ```
 
 ## Examples
 
-All custom geometies implement
+All custom geometries implement
 ```julia
 GeoInterface.isgeometry(geom::customgeom)::Bool = true
 ```

docs/src/index.md

@@ -11,13 +11,13 @@ CurrentModule = GeoInterface
 
 This Package describe a set of traits based on the [Simple Features standard (SF)](https://www.opengeospatial.org/standards/sfa)
 for geospatial vector data, including the SQL/MM extension with support for circular geometry.
-Using these traits, it should be easy to parse, serialize and use different geometries in the Julia ecosystem,
+By using these traits, it should be easy to parse, serialize and use different custom geometries in the Julia ecosystem,
 without knowing the specifics of each individual package. In that regard it is similar to Tables.jl, but for geometries instead of tables.
 
 Packages which support the GeoInterface.jl interface can be found in [Packages](@ref).
 
-For background about the interface and Simple Features, see [Changes with respect to SF](@ref).
 For usage see [Traits interface](@ref), while if you look to implement GeoInterface in your own package, check out [Implementing GeoInterface](@ref).
+For background about the interface and Simple Features, see [Changes with respect to SF](@ref).
 
 !!! compat
-    This traits interface is new and is a major departure from previous pre-1.0 releases. Feel free to ask questions on Github.
+    This traits interface is new and is a major departure from previous pre-1.0 releases. See [History](@ref) for more information. Feel free to ask questions on Github.

docs/src/tutorials/usage.md

@@ -47,6 +47,6 @@ julia> geomtype(ext)
 GeoInterface.LineStringTrait()
 julia> getcoords.(getpoint.(Ref(ext), 1:npoint(ext)))
 [[1.,2.],[2.,3.],[1.,2.]]
-julia> coords(geom)  # fallback based on ngeom & npoint above
+julia> coordinates(geom)  # fallback based on ngeom & npoint above
 
 ```

src/defaults.jl

@@ -95,6 +95,28 @@ function coordinates(::AbstractGeometryTrait, geom)
 end
 
 # Subtraits
+
+"""
+    subtrait(t::AbstractGeometryTrait)
+
+Gets the expected (sub)trait for subgeometries (retrieved with [`getgeom`](@ref)) of trait `t`.
+This follows the [Type hierarchy](@ref) of Simple Features.
+
+# Examples
+```jldoctest; setup = :(using GeoInterface)
+julia> GeoInterface.subtrait(GeoInterface.LineStringTrait())
+GeoInterface.PointTrait
+julia> GeoInterface.subtrait(GeoInterface.MultiPointTrait())
+GeoInterface.PointTrait
+```
+```jldoctest; setup = :(using GeoInterface)
+# `nothing` is returned when there's no subtrait or when it's not known beforehand
+julia> isnothing(GeoInterface.subtrait(GeoInterface.PointTrait()))
+true
+julia> isnothing(GeoInterface.subtrait(GeoInterface.GeometryCollectionTrait()))
+true
+```
+"""
 subtrait(::PointTrait) = nothing
 subtrait(::LineStringTrait) = PointTrait
 subtrait(::PolygonTrait) = LineStringTrait

test/runtests.jl

@@ -1,4 +1,6 @@
 using GeoInterface
+using Documenter
 using Test
 
 include("test_primitives.jl")
+doctest(GeoInterface)