[ios, macos] Added guide for working with GeoJSON

6 files changed, 97 insertions, 6 deletions

diff --git a/platform/darwin/docs/guides/Working with GeoJSON Data.md b/platform/darwin/docs/guides/Working with GeoJSON Data.md
new file mode 100644
index 0000000000..0fffed06dd
--- /dev/null
+++ b/platform/darwin/docs/guides/Working with GeoJSON Data.md
@@ -0,0 +1,89 @@
+# Working with GeoJSON Data
+
+This SDK offers several ways to work with [GeoJSON](http://geojson.org/) files.
+GeoJSON is a standard file format for representing geographic data.
+
+## Adding a GeoJSON file to the map
+
+You can use
+[Mapbox Studio’s Datasets editor](https://www.mapbox.com/studio/datasets/) to
+upload a GeoJSON file and include it in your custom map style. The GeoJSON data
+will be hosted on Mapbox servers. When a user loads your style, the SDK
+automatically loads the GeoJSON data for display.
+
+Alternatively, if you need to host the GeoJSON file elsewhere or bundle it with
+your application, you can use a GeoJSON file as the basis of an `MGLShapeSource`
+object. Pass the file’s URL into the
+`-[MGLShapeSource initWithIdentifier:URL:options:]` initializer and add the
+shape source to the map using the `-[MGLStyle addSource:]` method. The URL may
+be a local file URL, an HTTP URL, or an HTTPS URL.
+
+Once you’ve added the GeoJSON file to the map via an `MGLShapeSource` object,
+you can configure the appearance of its data and control what data is visible
+using `MGLStyleLayer` objects, you can
+[access the data programmatically](#Extracting GeoJSON data from the map).
+
+## Converting GeoJSON data into shape objects
+
+If you have GeoJSON data in the form of source code (also known as “GeoJSON
+text”), you can convert it into an `MGLShape`, `MGLFeature`, or
+`MGLShapeCollectionFeature` object that the `MGLShapeSource` class understands
+natively. First, create an `NSData` object out of the source code string or file
+contents, then pass that data object into the
+`+[MGLShape shapeWithData:encoding:error:]` method. Finally, you can pass the
+resulting shape or feature object into the
+`-[MGLShapeSource initWithIdentifier:shape:options:]` initializer and add it to
+the map, or you can use the object and its properties to power non-map-related
+functionality in your application.
+
+## Extracting GeoJSON data from the map
+
+Any `MGLShape`, `MGLFeature`, or `MGLShapeCollectionFeature` object has an
+`-[MGLShape geoJSONDataUsingEncoding:]` method that you can use to create a
+GeoJSON source code representation of the object. You can extract a feature
+object from the map using a method such as
+`-[MGLMapView visibleFeaturesAtPoint:]`.
+
+## About GeoJSON deserialization
+
+The process of converting GeoJSON text into `MGLShape`, `MGLFeature`, or
+`MGLShapeCollectionFeature` objects is known as “GeoJSON deserialization”.
+GeoJSON geometries, features, and feature collections are known in this SDK as
+shapes, features, and shape collection features, respectively.
+
+Each GeoJSON object type corresponds to a type provided by either this SDK or
+the Core Location framework:
+
+GeoJSON object type | SDK type
+--------------------|---------
+`Position` (longitude, latitude) | `CLLocationCoordinate2D` (latitude, longitude)
+`Point`             | `MGLPointAnnotation`
+`MultiPoint`        | `MGLPointCollection`
+`LineString`        | `MGLPolyline`
+`MultiLineString`   | `MGLMultiPolyline`
+`Polygon`           | `MGLPolygon`
+Linear ring         | `MGLPolygon.coordinates`, `MGLPolygon.interiorPolygons`
+`MultiPolygon`      | `MGLMultiPolygon`
+`GeometryCollection` | `MGLShapeCollection`
+`Feature`           | `MGLFeature`
+`FeatureCollection` | `MGLShapeCollectionFeature`
+
+A `Feature` object in GeoJSON corresponds to an instance of an `MGLShape`
+subclass conforming to the `MGLFeature` protocol. There is a distinct
+`MGLFeature`-conforming class for each type of geometry that a GeoJSON feature
+can contain. This allows features to be used as shapes where convenient. For
+example, some features can be added to a map view as annotations.
+
+In contrast to the GeoJSON standard, it is possible for `MGLShape` subclasses
+other than `MGLPointAnnotation` to straddle the antimeridian.
+
+The following GeoJSON data types correspond straightforwardly to Foundation data
+types when they occur as feature identifiers or property values:
+
+GeoJSON data type  | Objective-C representation | Swift representation
+-------------------|----------------------------|---------------------
+`null`             | `NSNull`                   | `NSNull`
+`true`, `false`    | `NSNumber.boolValue`       | `NSNumber.boolValue`
+Integer            | `NSNumber.unsignedLongLongValue`, `NSNumber.longLongValue` | `NSNumber.uint64Value`, `NSNumber.int64Value`
+Floating-point number | `NSNumber.doubleValue`  | `NSNumber.doubleValue`
+String             | `NSString`                 | `String`
diff --git a/platform/ios/jazzy.yml b/platform/ios/jazzy.yml
index 0a14cc3792..2473d0d1a3 100644
--- a/platform/ios/jazzy.yml
+++ b/platform/ios/jazzy.yml
@@ -21,6 +21,7 @@ custom_categories:
       - Runtime Styling
       - Working with Mapbox Studio
       - Info.plist Keys
+      - Working with GeoJSON Data
   - name: Maps
     children:
       - MGLAccountManager
diff --git a/platform/ios/scripts/document.sh b/platform/ios/scripts/document.sh
index ec349d592d..d66742a33f 100755
--- a/platform/ios/scripts/document.sh
+++ b/platform/ios/scripts/document.sh
@@ -41,7 +41,7 @@ jazzy \
     --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
     --module-version ${SHORT_VERSION} \
     --readme ${README} \
-    --documentation="platform/ios/docs/guides/*.md" \
+    --documentation="platform/{darwin,ios}/docs/guides/*.md" \
     --root-url https://www.mapbox.com/ios-sdk/api/${RELEASE_VERSION}/ \
     --theme ${THEME} \
     --output ${OUTPUT}
diff --git a/platform/macos/docs/Info.plist Keys.md b/platform/macos/docs/guides/Info.plist Keys.md
index a92b6fe296..f61ad8c7a7 100644
--- a/platform/macos/docs/Info.plist Keys.md
+++ b/platform/macos/docs/guides/Info.plist Keys.md
@@ -1,6 +1,6 @@
 # Info.plist Keys
 
-The Mapbox macOS SDK supports custom `Info.plist` keys in your application in order to configure various settings. 
+The Mapbox macOS SDK supports custom `Info.plist` keys in your application in order to configure various settings.
 
 ## MGLMapboxAccessToken
 
@@ -8,10 +8,10 @@ Set the [Mapbox access token](https://www.mapbox.com/help/define-access-token/)
 
 Mapbox-hosted vector tiles and styles require an API access token, which you can obtain from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access tokens associate requests to Mapbox’s vector tile and style APIs with your Mapbox account. They also deter other developers from using your styles without your permission.
 
-As an alternative, you can use `+[MGLAccountManager setAccessToken:]` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. 
+As an alternative, you can use `+[MGLAccountManager setAccessToken:]` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private.
 
 ## MGLMapboxAPIBaseURL
 
-Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. 
+Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used.
 
-The default value is `https://api.mapbox.com`. 
+The default value is `https://api.mapbox.com`.
diff --git a/platform/macos/jazzy.yml b/platform/macos/jazzy.yml
index 27202968ef..f237ba72bc 100644
--- a/platform/macos/jazzy.yml
+++ b/platform/macos/jazzy.yml
@@ -17,6 +17,7 @@ custom_categories:
   - name: Guides
     children:
       - Info.plist Keys
+      - Working with GeoJSON Data
   - name: Maps
     children:
       - MGLAccountManager
diff --git a/platform/macos/scripts/document.sh b/platform/macos/scripts/document.sh
index d03ad91674..22b7685c7e 100755
--- a/platform/macos/scripts/document.sh
+++ b/platform/macos/scripts/document.sh
@@ -38,7 +38,7 @@ jazzy \
     --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
     --module-version ${SHORT_VERSION} \
     --readme ${README} \
-    --documentation="platform/macos/docs/Info.plist Keys.md" \
+    --documentation="platform/{darwin,macos}/docs/guides/*.md" \
     --theme platform/darwin/docs/theme \
     --output ${OUTPUT}
 # https://github.com/realm/jazzy/issues/411