Merge pull request #162 from mapbox/1ec5-docs-turfjs

Generate API reference documentation

README.md

@@ -5,6 +5,7 @@
 📺[![tvOS](https://app.bitrise.io/app/0b037542c2395ffb/status.svg?token=yOtMqbu-5bj8grB1Jmoefg)](https://www.bitrise.io/app/0b037542c2395ffb)    
 ⌚️[![watchOS](https://app.bitrise.io/app/0d4d611f02295183/status.svg?token=NiLB_E_0IvYYqV4Mj973TQ)](https://www.bitrise.io/app/0d4d611f02295183)    
 <img src="https://upload.wikimedia.org/wikipedia/commons/3/3c/TuxFlat.svg" width="20" alt="Linux">[![](https://api.travis-ci.com/mapbox/turf-swift.svg?branch=main)](https://travis-ci.com/mapbox/turf-swift) &nbsp;&nbsp;&nbsp;
+[![](https://mapbox.github.io/turf-swift/1.2.0/badge.svg)](https://mapbox.github.io/turf-swift/) &nbsp;&nbsp;&nbsp;
 [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage) &nbsp;&nbsp;&nbsp;
 [![CocoaPods](https://img.shields.io/cocoapods/v/Turf.svg)](http://cocoadocs.org/docsets/Turf/) &nbsp;&nbsp;&nbsp;
 [![SPM compatible](https://img.shields.io/badge/SPM-compatible-4BC51D.svg?style=flat)](https://swift.org/package-manager/) &nbsp;&nbsp;&nbsp;
@@ -67,34 +68,33 @@ Then `import Turf` in any Swift file in your module.
 
 This work-in-progress port of [Turf.js](https://github.com/Turfjs/turf/) contains the following functionality:
 
-Turf.js | Turf-swift
+Turf.js | Turf for Swift
 ----|----
-[turf-along](https://github.com/Turfjs/turf/tree/master/packages/turf-along/) | `LineString.coordinateFromStart(distance:)`
-[turf-area](https://github.com/Turfjs/turf/blob/master/packages/turf-area/) | `Polygon.area`
-[turf-bearing](https://turfjs.org/docs/#bearing) | `CLLocationCoordinate2D.direction(to:)`<br>`LocationCoordinate2D.direction(to:)` on Linux<br>`RadianCoordinate2D.direction(to:)`
-[turf-bezier-spline](https://github.com/Turfjs/turf/tree/master/packages/turf-bezier-spline/) | `LineString.bezier(resolution:sharpness:)`
-[turf-boolean-point-in-polygon](https://github.com/Turfjs/turf/tree/master/packages/turf-boolean-point-in-polygon) | `Polygon.contains(_:ignoreBoundary:)`
-[turf-center](http://turfjs.org/docs/#center) | `Polygon.center`
-[turf-center-of-mass](http://turfjs.org/docs/#centerOfMass) | `Polygon.centerOfMass`
-[turf-centroid](http://turfjs.org/docs/#centroid) | `Polygon.centroid`
-[turf-circle](https://turfjs.org/docs/#circle) | `Polygon(center:radius:vertices:)` |
-[turf-destination](https://github.com/Turfjs/turf/tree/master/packages/turf-destination/) | `CLLocationCoordinate2D.coordinate(at:facing:)`<br>`LocationCoordinate2D.coordinate(at:facing:)` on Linux<br>`RadianCoordinate2D.coordinate(at:facing:)`
-[turf-distance](https://github.com/Turfjs/turf/tree/master/packages/turf-distance/) | `CLLocationCoordinate2D.distance(to:)`<br>`LocationCoordinate2D.distance(to:)` on Linux<br>`RadianCoordinate2D.distance(to:)`
-[turf-helpers#polygon](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers/#polygon) | `Polygon(_:)`
-[turf-helpers#lineString](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers/#linestring) | `LineString(_:)`
-[turf-helpers#degreesToRadians](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers/#degreesToRadians) | `CLLocationDegrees.toRadians()`<br>`LocationDegrees.toRadians()` on Linux
-[turf-helpers#radiansToDegrees](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers/#radiansToDegrees) | `CLLocationDegrees.toDegrees()`<br>`LocationDegrees.toDegrees()` on Linux
-[turf-helpers#convertLength](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers#convertlength)<br>[turf-helpers#convertArea](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers#convertarea) | `Measurement.converted(to:)`
-[turf-length](https://github.com/Turfjs/turf/tree/master/packages/turf-length/) | `LineString.distance(from:to:)`
-[turf-line-intersect](https://github.com/Turfjs/turf/tree/master/packages/turf-line-intersect/) | `intersection(_:_:)`
-[turf-line-slice](https://github.com/Turfjs/turf/tree/master/packages/turf-line-slice/) | `LineString.sliced(from:to:)`
-[turf-line-slice-along](https://github.com/Turfjs/turf/tree/master/packages/turf-line-slice-along/) | `LineString.trimmed(from:distance:)`
-[turf-midpoint](https://github.com/Turfjs/turf/blob/master/packages/turf-midpoint/index.js) | `mid(_:_:)`
-[turf-nearest-point-on-line](https://github.com/Turfjs/turf/tree/master/packages/turf-nearest-point-on-line/) | `LineString.closestCoordinate(to:)`
-[turf-polygon-to-line](https://github.com/Turfjs/turf/tree/master/packages/turf-polygon-to-line/) | `LineString(_:)`<br>`MultiLineString(_:)`<br>`FeatureCollection(_:)`
-[turf-simplify](https://github.com/Turfjs/turf/tree/master/packages/turf-simplify) | `LineString.simplified(tolerance:highestQuality:)`
-[turf-polygon-smooth](https://github.com/Turfjs/turf/tree/master/packages/turf-polygon-smooth) | `Polygon.smooth(iterations:)`
-[turf-simplify](https://github.com/Turfjs/turf/tree/master/packages/turf-simplify) | `Polygon.simplified(tolerance:highestQuality:)`
+[turf-along#along](https://turfjs.org/docs/#along) | `LineString.coordinateFromStart(distance:)`
+[turf-area#area](https://turfjs.org/docs/#area) | `Polygon.area`
+[turf-bearing#bearing](https://turfjs.org/docs/#bearing) | `CLLocationCoordinate2D.direction(to:)`<br>`LocationCoordinate2D.direction(to:)` on Linux<br>`RadianCoordinate2D.direction(to:)`
+[turf-bezier-spline#bezierSpline](https://turfjs.org/docs/#bezierSpline) | `LineString.bezier(resolution:sharpness:)`
+[turf-boolean-point-in-polygon#booleanPointInPolygon](https://turfjs.org/docs/#booleanPointInPolygon) | `Polygon.contains(_:ignoreBoundary:)`
+[turf-center#center](https://turfjs.org/docs/#center) | `Polygon.center`
+[turf-center-of-mass#centerOfMass](https://turfjs.org/docs/#centerOfMass) | `Polygon.centerOfMass`
+[turf-centroid#centroid](https://turfjs.org/docs/#centroid) | `Polygon.centroid`
+[turf-circle#circle](https://turfjs.org/docs/#circle) | `Polygon(center:radius:vertices:)` |
+[turf-destination#destination](https://turfjs.org/docs/#destination) | `CLLocationCoordinate2D.coordinate(at:facing:)`<br>`LocationCoordinate2D.coordinate(at:facing:)` on Linux<br>`RadianCoordinate2D.coordinate(at:facing:)`
+[turf-distance#distance](https://turfjs.org/docs/#distance) | `CLLocationCoordinate2D.distance(to:)`<br>`LocationCoordinate2D.distance(to:)` on Linux<br>`RadianCoordinate2D.distance(to:)`
+[turf-helpers#polygon](https://turfjs.org/docs/#polygon) | `Polygon(_:)`
+[turf-helpers#lineString](https://turfjs.org/docs/#lineString) | `LineString(_:)`
+[turf-helpers#degreesToRadians](https://turfjs.org/docs/#degreesToRadians) | `CLLocationDegrees.toRadians()`<br>`LocationDegrees.toRadians()` on Linux
+[turf-helpers#radiansToDegrees](https://turfjs.org/docs/#radiansToDegrees) | `CLLocationDegrees.toDegrees()`<br>`LocationDegrees.toDegrees()` on Linux
+[turf-helpers#convertLength](https://turfjs.org/docs/#convertLength)<br>[turf-helpers#convertArea](https://turfjs.org/docs/#convertArea) | `Measurement.converted(to:)`
+[turf-length#length](https://turfjs.org/docs/#length) | `LineString.distance(from:to:)`
+[turf-line-intersect#lineIntersect](https://turfjs.org/docs/#lineIntersect) | `intersection(_:_:)`
+[turf-line-slice#lineSlice](https://turfjs.org/docs/#lineSlice) | `LineString.sliced(from:to:)`
+[turf-line-slice-along#lineSliceAlong](https://turfjs.org/docs/#lineSliceAlong) | `LineString.trimmed(from:distance:)`
+[turf-midpoint#midpoint](https://turfjs.org/docs/#midpoint) | `mid(_:_:)`
+[turf-nearest-point-on-line#nearestPointOnLine](https://turfjs.org/docs/#nearestPointOnLine) | `LineString.closestCoordinate(to:)`
+[turf-polygon-to-line#polygonToLine](https://turfjs.org/docs/#polygonToLine) | `LineString(_:)`<br>`MultiLineString(_:)`
+[turf-simplify#simplify](https://turfjs.org/docs/#simplify) | `LineString.simplify(tolerance:highestQuality:)`<br>`LineString.simplified(tolerance:highestQuality:)`
+[turf-polygon-smooth#polygonSmooth](https://turfjs.org/docs/#polygonSmooth) | `Polygon.smooth(iterations:)`
 — | `CLLocationDirection.difference(from:)`<br>`LocationDirection.difference(from:)` on Linux
 — | `CLLocationDirection.wrap(min:max:)`<br>`LocationDirection.wrap(min:max:)` on Linux
 

Sources/Turf/CoreLocation.swift

@@ -107,13 +107,17 @@ extension LocationDirection {
 extension LocationDegrees {
     /**
      Returns the direction in radians.
+
+     This method is equivalent to the [`degreesToRadians`](https://turfjs.org/docs/#degreesToRadians) method of the turf-helpers package of Turf.js ([source code](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers/)).
      */
     public func toRadians() -> LocationRadians {
         return self * .pi / 180.0
     }
 
     /**
      Returns the direction in degrees.
+
+     This method is equivalent to the [`radiansToDegrees`](https://turfjs.org/docs/#radiansToDegrees) method of the turf-helpers package of Turf.js ([source code](https://github.com/Turfjs/turf/tree/master/packages/turf-helpers/)).
      */
     public func toDegrees() -> LocationDirection {
         return self * 180.0 / .pi
@@ -198,7 +202,11 @@ extension LocationCoordinate2D: Equatable {
         return lhs.latitude == rhs.latitude && lhs.longitude == rhs.longitude
     }
 
-    /// Returns the direction from the receiver to the given coordinate.
+    /**
+     Returns the direction from the receiver to the given coordinate.
+
+     This method is equivalent to the [turf-bearing](https://turfjs.org/docs/#bearing) package of Turf.js ([source code](https://github.com/Turfjs/turf/tree/master/packages/turf-bearing/)).
+     */
     public func direction(to coordinate: LocationCoordinate2D) -> LocationDirection {
         return RadianCoordinate2D(self).direction(to: RadianCoordinate2D(coordinate)).converted(to: .degrees).value
     }
@@ -209,14 +217,20 @@ extension LocationCoordinate2D: Equatable {
         return coordinate(at: distance, facing: angle)
     }
 
-    /// Returns a coordinate a certain Haversine distance away in the given direction.
+    /**
+     Returns a coordinate a certain Haversine distance away in the given direction.
+
+     This method is equivalent to the [turf-destination](https://turfjs.org/docs/#destination) package of Turf.js ([source code](https://github.com/Turfjs/turf/tree/master/packages/turf-destination/)).
+     */
     public func coordinate(at distance: LocationDistance, facing direction: Measurement<UnitAngle>) -> LocationCoordinate2D {
         let radianCoordinate = RadianCoordinate2D(self).coordinate(at: distance / metersPerRadian, facing: direction)
         return LocationCoordinate2D(radianCoordinate)
     }
 
     /**
      Returns the Haversine distance between two coordinates measured in degrees.
+
+     This method is equivalent to the [turf-distance](https://turfjs.org/docs/#distance) package of Turf.js ([source code](https://github.com/Turfjs/turf/tree/master/packages/turf-distance/)).
      */
     public func distance(to coordinate: LocationCoordinate2D) -> LocationDistance {
         return RadianCoordinate2D(self).distance(to: RadianCoordinate2D(coordinate)) * metersPerRadian

Sources/Turf/Feature.swift

@@ -7,10 +7,24 @@ import CoreLocation
  A [Feature object](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2) represents a spatially bounded thing.
  */
 public struct Feature: Equatable {
+    /**
+     A string or number that commonly identifies the feature in the context of a data set.
+
+     Turf does not guarantee that the feature is unique; however, a data set may make such a guarantee.
+     */
     public var identifier: FeatureIdentifier?
+
+    /// Arbitrary, JSON-compatible attributes to associate with the feature.
     public var properties: JSONObject?
+
+    /// The geometry at which the feature is located.
     public var geometry: Geometry?
 
+    /**
+     Initializes a feature located at the given geometry.
+
+     - parameter geometry: The geometry at which the feature is located.
+     */
     public init(geometry: Geometry?) {
         self.geometry = geometry
     }

Sources/Turf/FeatureCollection.swift

@@ -4,8 +4,14 @@ import Foundation
  A [FeatureCollection object](https://datatracker.ietf.org/doc/html/rfc7946#section-3.3) is a collection of Feature objects.
  */
 public struct FeatureCollection: Equatable {
-    public var features: Array<Feature> = []
+    /// The features that the collection contains.
+    public var features: [Feature] = []
 
+    /**
+     Initializes a feature collection containing the given features.
+
+     - parameter features: The features that the collection contains.
+     */
     public init(features: [Feature]) {
         self.features = features
     }