📖 Add documentation to GeoJSON

RemiBardon · RemiBardon · commit 5c9019472e53 · 2022-02-09T15:30:45.000+01:00
diff --git a/Sources/GeoJSON/BoundingBox.swift b/Sources/GeoJSON/BoundingBox.swift
@@ -8,12 +8,15 @@
 
 import GeoModels
 
+/// A [GeoJSON Bounding Box](https://datatracker.ietf.org/doc/html/rfc7946#section-5).
 public protocol BoundingBox: Hashable, Codable {
 	
+	/// This bonding box, but type-erased.
 	var asAny: AnyBoundingBox { get }
 	
 }
 
+/// A two-dimensional ``BoundingBox``.
 public typealias BoundingBox2D = GeoModels.BoundingBox2D
 
 extension BoundingBox2D: BoundingBox {
@@ -22,6 +25,7 @@ extension BoundingBox2D: BoundingBox {
 	
 }
 
+/// A three-dimensional ``BoundingBox``.
 public typealias BoundingBox3D = GeoModels.BoundingBox3D
 
 extension BoundingBox3D: BoundingBox {
@@ -30,6 +34,7 @@ extension BoundingBox3D: BoundingBox {
 	
 }
 
+/// A type-erased ``BoundingBox``.
 public enum AnyBoundingBox: BoundingBox, Hashable, Codable {
 	
 	case twoDimensions(BoundingBox2D)
diff --git a/Sources/GeoJSON/Errors.swift b/Sources/GeoJSON/Errors.swift
@@ -8,6 +8,8 @@
 
 import Foundation
 
+/// Error when creating ``LinearRingCoordinates``.
+///
 /// See [RFC 7946, section 3.1.6](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6).
 public enum LinearRingError: Error {
 	case firstAndLastPositionsShouldBeEquivalent
diff --git a/Sources/GeoJSON/FeatureProperties.swift b/Sources/GeoJSON/FeatureProperties.swift
@@ -0,0 +1,10 @@
+//
+//  FeatureProperties.swift
+//  GeoSwift
+//
+//  Created by Rémi Bardon on 04/02/2022.
+//  Copyright © 2022 Rémi Bardon. All rights reserved.
+//
+
+/// The `"properties"` field of a [GeoJSON Feature](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2).
+public typealias FeatureProperties = Codable & Hashable
diff --git a/Sources/GeoJSON/GeoJSON.docc/Documentation.md b/Sources/GeoJSON/GeoJSON.docc/Documentation.md
@@ -0,0 +1,27 @@
+# ``GeoJSON``
+
+## Topics
+
+### Positions
+
+- ``Position``
+- ``Position2D``
+- ``Position3D``
+
+### Types
+
+- <doc:Types>
+
+### Objects
+
+- ``Object``
+- <doc:Geometries>
+- ``Feature``
+- ``FeatureCollection``
+
+### Bounding Boxes
+
+- ``BoundingBox``
+- ``BoundingBox2D``
+- ``BoundingBox3D``
+- ``AnyBoundingBox``
diff --git a/Sources/GeoJSON/GeoJSON.docc/Geometries.md b/Sources/GeoJSON/GeoJSON.docc/Geometries.md
@@ -0,0 +1,54 @@
+# Geometries
+
+## Topics
+
+### Base
+
+- ``Geometry``
+- ``AnyGeometry``
+
+### Introduced concepts
+
+- ``SingleGeometry``
+- ``LinearRingCoordinates``
+- ``LinearRingError``
+
+### Point
+
+- ``Point``
+- ``Point2D``
+- ``Point3D``
+
+### MultiPoint
+
+- ``MultiPoint``
+- ``MultiPoint2D``
+- ``MultiPoint3D``
+
+### LineString
+
+- ``LineString``
+- ``LineString2D``
+- ``LineString3D``
+
+### MultiLineString
+
+- ``MultiLineString``
+- ``MultiLineString2D``
+- ``MultiLineString3D``
+
+### Polygon
+
+- ``Polygon``
+- ``Polygon2D``
+- ``Polygon3D``
+
+### MultiPolygon
+
+- ``MultiPolygon``
+- ``MultiPolygon2D``
+- ``MultiPolygon3D``
+
+### GeometryCollection
+
+- ``GeometryCollection``
diff --git a/Sources/GeoJSON/GeoJSON.docc/Types.md b/Sources/GeoJSON/GeoJSON.docc/Types.md
@@ -0,0 +1,20 @@
+# Types
+
+## Topics
+
+### Enums
+
+- ``Type``
+- ``Type/Geometry``
+
+### Cases
+
+- ``Type/Geometry/point``
+- ``Type/Geometry/multiPoint``
+- ``Type/Geometry/lineString``
+- ``Type/Geometry/multiLineString``
+- ``Type/Geometry/polygon``
+- ``Type/Geometry/multiPolygon``
+- ``Type/Geometry/geometryCollection``
+- ``Type/feature``
+- ``Type/featureCollection``
diff --git a/Sources/GeoJSON/Geometries/GeometryCollection.swift b/Sources/GeoJSON/Geometries/GeometryCollection.swift
@@ -6,9 +6,10 @@
 //  Copyright © 2022 Rémi Bardon. All rights reserved.
 //
 
+/// A [GeoJSON GeometryCollection](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.8).
 public struct GeometryCollection: Geometry {
 	
-	public static var geometryType: GeoJSON.`Type`.Geometry { .geometryCollection}
+	public static var geometryType: GeoJSON.`Type`.Geometry { .geometryCollection }
 	
 	public var bbox: AnyBoundingBox?
 	
diff --git a/Sources/GeoJSON/Geometries/LineString.swift b/Sources/GeoJSON/Geometries/LineString.swift
@@ -8,13 +8,15 @@
 
 import NonEmpty
 
+/// A [GeoJSON LineString](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4).
 public protocol LineString: SingleGeometry {
 	
 	associatedtype Position: GeoJSON.Position
 	associatedtype Coordinates = NonEmpty<NonEmpty<[Position]>>
 	
 }
 
+/// A ``LineString`` with ``Point2D``s.
 public struct LineString2D: LineString {
 	
 	public typealias Position = Position2D
@@ -39,6 +41,7 @@ public struct LineString2D: LineString {
 	
 }
 
+/// A ``LineString`` with ``Point3D``s.
 public struct LineString3D: LineString {
 	
 	public typealias Position = Position3D
diff --git a/Sources/GeoJSON/Geometries/MultiLineString.swift b/Sources/GeoJSON/Geometries/MultiLineString.swift
@@ -8,13 +8,15 @@
 
 import NonEmpty
 
+/// A [GeoJSON MultiLineString](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.5).
 public protocol MultiLineString: SingleGeometry {
 	
 	associatedtype LineString: GeoJSON.LineString
 	associatedtype Coordinates = [LineString.Coordinates]
 	
 }
 
+/// A ``MultiLineString`` with ``Point2D``s.
 public struct MultiLineString2D: MultiLineString {
 	
 	public typealias LineString = LineString2D
@@ -45,6 +47,7 @@ public struct MultiLineString2D: MultiLineString {
 	
 }
 
+/// A ``MultiLineString`` with ``Point3D``s.
 public struct MultiLineString3D: MultiLineString {
 	
 	public typealias LineString = LineString3D
diff --git a/Sources/GeoJSON/Geometries/MultiPoint.swift b/Sources/GeoJSON/Geometries/MultiPoint.swift
@@ -6,13 +6,15 @@
 //  Copyright © 2022 Rémi Bardon. All rights reserved.
 //
 
+/// A [GeoJSON MultiPoint](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.3).
 public protocol MultiPoint: SingleGeometry {
 	
 	associatedtype Point: GeoJSON.Point
 	associatedtype Coordinates = [Point.Coordinates]
 	
 }
 
+/// A ``MultiPoint`` with ``Point2D``s.
 public struct MultiPoint2D: MultiPoint {
 	
 	public typealias Point = Point2D
@@ -29,6 +31,7 @@ public struct MultiPoint2D: MultiPoint {
 	
 }
 
+/// A ``MultiPoint`` with ``Point3D``s.
 public struct MultiPoint3D: MultiPoint {
 	
 	public typealias Point = Point3D
diff --git a/Sources/GeoJSON/Geometries/MultiPolygon.swift b/Sources/GeoJSON/Geometries/MultiPolygon.swift
@@ -6,13 +6,15 @@
 //  Copyright © 2022 Rémi Bardon. All rights reserved.
 //
 
+/// A [GeoJSON MultiPolygon](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.7).
 public protocol MultiPolygon: SingleGeometry {
 	
 	associatedtype Polygon: GeoJSON.Polygon
 	associatedtype Coordinates = [Polygon.Coordinates]
 	
 }
 
+/// A ``MultiPolygon`` with ``Point2D``s.
 public struct MultiPolygon2D: MultiPolygon {
 	
 	public typealias Polygon = Polygon2D
@@ -29,6 +31,7 @@ public struct MultiPolygon2D: MultiPolygon {
 	
 }
 
+/// A ``MultiPolygon`` with ``Point3D``s.
 public struct MultiPolygon3D: MultiPolygon {
 	
 	public typealias Polygon = Polygon3D
diff --git a/Sources/GeoJSON/Geometries/Point.swift b/Sources/GeoJSON/Geometries/Point.swift
@@ -6,13 +6,15 @@
 //  Copyright © 2022 Rémi Bardon. All rights reserved.
 //
 
+/// A [GeoJSON Point](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.2).
 public protocol Point: SingleGeometry {
 	
 	associatedtype Position: GeoJSON.Position
 	associatedtype Coordinates = Position
 	
 }
 
+/// A two-dimensional ``Point`` (with longitude and latitude).
 public struct Point2D: Point {
 	
 	public typealias Position = Position2D
@@ -29,6 +31,7 @@ public struct Point2D: Point {
 	
 }
 
+/// A three-dimensional ``Point`` (with longitude, latitude and altitude).
 public struct Point3D: Point {
 	
 	public typealias Position = Position3D
diff --git a/Sources/GeoJSON/Geometries/Polygon.swift b/Sources/GeoJSON/Geometries/Polygon.swift
@@ -9,6 +9,7 @@
 import NonEmpty
 import Turf
 
+/// A [GeoJSON Polygon](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6) / linear ring.
 public protocol Polygon: SingleGeometry {
 	
 	associatedtype Point: GeoJSON.Point
@@ -55,7 +56,7 @@ extension LinearRingCoordinates: ExpressibleByArrayLiteral {
 	
 }
 
-/// A 2D polygon / linear ring.
+/// A ``Polygon`` with ``Point2D``s.
 public struct Polygon2D: Polygon {
 	
 	public typealias Point = Point2D
@@ -72,7 +73,7 @@ public struct Polygon2D: Polygon {
 	
 }
 
-/// A 3D polygon / linear ring.
+/// A ``Polygon`` with ``Point3D``s.
 public struct Polygon3D: Polygon {
 	
 	public typealias Point = Point3D
diff --git a/Sources/GeoJSON/Objects/Feature.swift b/Sources/GeoJSON/Objects/Feature.swift
@@ -6,10 +6,11 @@
 //  Copyright © 2022 Rémi Bardon. All rights reserved.
 //
 
+/// A [GeoJSON Feature](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2).
 public struct Feature<
 //	Geometry: GeoJSON.Geometry,
 //	BoundingBox: GeoJSON.BoundingBox,
-	Properties: GeoJSON.Properties
+	Properties: GeoJSON.FeatureProperties
 >: GeoJSON.Object {
 	
 	public static var geoJSONType: GeoJSON.`Type` { .feature }
diff --git a/Sources/GeoJSON/Objects/FeatureCollection.swift b/Sources/GeoJSON/Objects/FeatureCollection.swift
@@ -6,9 +6,10 @@
 //  Copyright © 2022 Rémi Bardon. All rights reserved.
 //
 
+/// A [GeoJSON FeatureCollection](https://datatracker.ietf.org/doc/html/rfc7946#section-3.3).
 public struct FeatureCollection<
 //	BoundingBox: GeoJSON.BoundingBox,
-	Properties: GeoJSON.Properties
+	Properties: GeoJSON.FeatureProperties
 >: GeoJSON.Object {
 	
 	public static var geoJSONType: GeoJSON.`Type` { .featureCollection }
diff --git a/Sources/GeoJSON/Objects/Geometry.swift b/Sources/GeoJSON/Objects/Geometry.swift
@@ -8,12 +8,15 @@
 
 import Turf
 
+/// A [GeoJSON Geometry](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1).
 public protocol Geometry: GeoJSON.Object {
 	
+	/// The GeoJSON type of this geometry.
 	static var geometryType: GeoJSON.`Type`.Geometry { get }
 	
 	var bbox: BoundingBox? { get }
 	
+	/// This geometry, but type-erased.
 	var asAnyGeometry: AnyGeometry { get }
 	
 }
@@ -24,6 +27,8 @@ extension Geometry {
 	
 }
 
+/// A single [GeoJSON Geometry](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1)
+/// (not a [GeometryCollection](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.8)).
 public protocol SingleGeometry: Geometry {
 	
 	associatedtype Coordinates: Boundable & Hashable & Codable
@@ -41,6 +46,7 @@ extension SingleGeometry {
 	
 }
 
+/// A type-erased ``Geometry``.
 public enum AnyGeometry: Hashable, Codable {
 	
 	case geometryCollection(GeometryCollection)
diff --git a/Sources/GeoJSON/Objects/Object.swift b/Sources/GeoJSON/Objects/Object.swift
@@ -6,10 +6,13 @@
 //  Copyright © 2022 Rémi Bardon. All rights reserved.
 //
 
+/// A [GeoJSON Object](https://datatracker.ietf.org/doc/html/rfc7946#section-3).
 public protocol Object: Hashable, Codable {
 	
 	associatedtype BoundingBox: GeoJSON.BoundingBox
 	
+	/// The [GeoJSON type](https://datatracker.ietf.org/doc/html/rfc7946#section-1.4) of this
+	/// [GeoJSON object](https://datatracker.ietf.org/doc/html/rfc7946#section-3).
 	static var geoJSONType: GeoJSON.`Type` { get }
 	
 	var bbox: BoundingBox? { get }
diff --git a/Sources/GeoJSON/Position.swift b/Sources/GeoJSON/Position.swift
diff --git a/Sources/GeoJSON/Properties.swift b/Sources/GeoJSON/Properties.swift
diff --git a/Sources/GeoJSON/Type.swift b/Sources/GeoJSON/Type.swift

Original file line number	Diff line number	Diff line change
`@@ -8,12 +8,15 @@`
`8`	`8`
`9`	`9`	`import GeoModels`
`10`	`10`
	`11`	`+/// A [GeoJSON Bounding Box](https://datatracker.ietf.org/doc/html/rfc7946#section-5).`
`11`	`12`	`public protocol BoundingBox: Hashable, Codable {`
`12`	`13`
	`14`	`+ /// This bonding box, but type-erased.`
`13`	`15`	`var asAny: AnyBoundingBox { get }`
`14`	`16`
`15`	`17`	`}`
`16`	`18`
	`19`	+/// A two-dimensional ``BoundingBox``.
`17`	`20`	`public typealias BoundingBox2D = GeoModels.BoundingBox2D`
`18`	`21`
`19`	`22`	`extension BoundingBox2D: BoundingBox {`
`@@ -22,6 +25,7 @@ extension BoundingBox2D: BoundingBox {`
`22`	`25`
`23`	`26`	`}`
`24`	`27`
	`28`	+/// A three-dimensional ``BoundingBox``.
`25`	`29`	`public typealias BoundingBox3D = GeoModels.BoundingBox3D`
`26`	`30`
`27`	`31`	`extension BoundingBox3D: BoundingBox {`
`@@ -30,6 +34,7 @@ extension BoundingBox3D: BoundingBox {`
`30`	`34`
`31`	`35`	`}`
`32`	`36`
	`37`	+/// A type-erased ``BoundingBox``.
`33`	`38`	`public enum AnyBoundingBox: BoundingBox, Hashable, Codable {`
`34`	`39`
`35`	`40`	`case twoDimensions(BoundingBox2D)`
Original file line number	Diff line number	Diff line change
`@@ -8,13 +8,15 @@`
`8`	`8`
`9`	`9`	`import NonEmpty`
`10`	`10`
	`11`	`+/// A [GeoJSON LineString](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4).`
`11`	`12`	`public protocol LineString: SingleGeometry {`
`12`	`13`
`13`	`14`	`associatedtype Position: GeoJSON.Position`
`14`	`15`	`associatedtype Coordinates = NonEmpty<NonEmpty<[Position]>>`
`15`	`16`
`16`	`17`	`}`
`17`	`18`
	`19`	+/// A ``LineString`` with ``Point2D``s.
`18`	`20`	`public struct LineString2D: LineString {`
`19`	`21`
`20`	`22`	`public typealias Position = Position2D`
`@@ -39,6 +41,7 @@ public struct LineString2D: LineString {`
`39`	`41`
`40`	`42`	`}`
`41`	`43`
	`44`	+/// A ``LineString`` with ``Point3D``s.
`42`	`45`	`public struct LineString3D: LineString {`
`43`	`46`
`44`	`47`	`public typealias Position = Position3D`