[ios, macos] flesh out iOS runtime styling docs (#6466)

- fixes #5959: MGLBaseStyleLayer docs
- fixes #5960: MGLSource & subclasses docs
- fixes #6467: concrete layer subclass docs
- move Core Graphics include
- slight code & template cleanups
- add ./documentation to git ignores

16 files changed, 176 insertions, 15 deletions

diff --git a/.gitignore b/.gitignore
index eb0800bb4d..ecd9b7ec57 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,3 +29,4 @@ xcuserdata
 **/token
 /platform/macos/macos.xcworkspace/xcshareddata/macos.xcscmblueprint
 /platform/ios/ios.xcworkspace/xcshareddata/ios.xcscmblueprint
+/documentation
diff --git a/platform/darwin/src/MGLBackgroundStyleLayer.h b/platform/darwin/src/MGLBackgroundStyleLayer.h
index a6eda28783..386b68feda 100644
--- a/platform/darwin/src/MGLBackgroundStyleLayer.h
+++ b/platform/darwin/src/MGLBackgroundStyleLayer.h
@@ -6,6 +6,12 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ A map style's background layer is the bottommost layer and is used to style a color 
+ or pattern to show below all other map features. You can query an `MGLMapView` for its 
+ `style` and obtain the background layer using the `-[MGLStyle layerWithIdentifier:]` 
+ method and passing `background` for the identifier. 
+ */
 @interface MGLBackgroundStyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
 
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier;
diff --git a/platform/darwin/src/MGLBaseStyleLayer.h b/platform/darwin/src/MGLBaseStyleLayer.h
index e561af5c68..6cd525a0fd 100644
--- a/platform/darwin/src/MGLBaseStyleLayer.h
+++ b/platform/darwin/src/MGLBaseStyleLayer.h
@@ -4,17 +4,29 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ The base style layer class from which all other style layer classes 
+ inherit. Style layers allow runtime customization of all map styling 
+ properties.
+ 
+ You should use the concrete subclasses of `MGLBaseStyleLayer` (which
+ conform to `MGLStyleLayer`) to style fill, line, symbol, and other layer 
+ types.
+ */
 @interface MGLBaseStyleLayer : NSObject
 
+/**
+ The display of the layer. A value of `NO` hides the layer.
+ */
 @property (nonatomic, assign, getter=isVisible) BOOL visible;
 
 /**
- The maximum zoom level on which the layer gets parsed and appears on.
+ The maximum zoom level at which the layer gets parsed and appears.
  */
 @property (nonatomic, assign) float maximumZoomLevel;
 
 /**
- The minimum zoom level on which the layer gets parsed and appears on.
+ The minimum zoom level at which the layer gets parsed and appears.
  */
 @property (nonatomic, assign) float minimumZoomLevel;
 
diff --git a/platform/darwin/src/MGLCircleStyleLayer.h b/platform/darwin/src/MGLCircleStyleLayer.h
index 5492b183f4..2cda065b52 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.h
+++ b/platform/darwin/src/MGLCircleStyleLayer.h
@@ -16,9 +16,14 @@ typedef NS_ENUM(NSUInteger, MGLCircleStyleLayerCirclePitchScale) {
     MGLCircleStyleLayerCirclePitchScaleViewport,
 };
 
+/**
+ A circle layer which allows customization of styling properties at runtime. You may 
+ instantiate a new circle layer to add to a map style or you may query an 
+ `MGLMapView` for its `style` and obtain existing layers using the 
+ `-[MGLStyle layerWithIdentifier:]` method. 
+ */
 @interface MGLCircleStyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
 
-
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source;
 
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source sourceLayer:(NSString *)sourceLayer;
diff --git a/platform/darwin/src/MGLFillStyleLayer.h b/platform/darwin/src/MGLFillStyleLayer.h
index 823c0574af..ab30efff5c 100644
--- a/platform/darwin/src/MGLFillStyleLayer.h
+++ b/platform/darwin/src/MGLFillStyleLayer.h
@@ -11,9 +11,14 @@ typedef NS_ENUM(NSUInteger, MGLFillStyleLayerFillTranslateAnchor) {
     MGLFillStyleLayerFillTranslateAnchorViewport,
 };
 
+/**
+ A fill layer which allows customization of styling properties at runtime. You may 
+ instantiate a new fill layer to add to a map style or you may query an 
+ `MGLMapView` for its `style` and obtain existing layers using the 
+ `-[MGLStyle layerWithIdentifier:]` method. 
+ */
 @interface MGLFillStyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
 
-
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source;
 
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source sourceLayer:(NSString *)sourceLayer;
diff --git a/platform/darwin/src/MGLLineStyleLayer.h b/platform/darwin/src/MGLLineStyleLayer.h
index ec338f65b6..58c601d53c 100644
--- a/platform/darwin/src/MGLLineStyleLayer.h
+++ b/platform/darwin/src/MGLLineStyleLayer.h
@@ -23,9 +23,14 @@ typedef NS_ENUM(NSUInteger, MGLLineStyleLayerLineTranslateAnchor) {
     MGLLineStyleLayerLineTranslateAnchorViewport,
 };
 
+/**
+ A line layer which allows customization of styling properties at runtime. You may 
+ instantiate a new line layer to add to a map style or you may query an 
+ `MGLMapView` for its `style` and obtain existing layers using the 
+ `-[MGLStyle layerWithIdentifier:]` method. 
+ */
 @interface MGLLineStyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
 
-
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source;
 
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source sourceLayer:(NSString *)sourceLayer;
diff --git a/platform/darwin/src/MGLRasterSource.h b/platform/darwin/src/MGLRasterSource.h
index 3b22257cb6..bf561df8da 100644
--- a/platform/darwin/src/MGLRasterSource.h
+++ b/platform/darwin/src/MGLRasterSource.h
@@ -1,19 +1,64 @@
 #import "MGLSource.h"
 #import "MGLTypes.h"
 
+#import <CoreGraphics/CoreGraphics.h>
+
 @class MGLTileSet;
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ A raster tile source.
+ 
+ @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-raster">The
+ style specification.</a>
+ */
 @interface MGLRasterSource : MGLSource
 
+/**
+ A URL to a TileJSON resource. Supported protocols are `http:`, `https:`, and 
+ `mapbox://<mapid>`.
+ 
+ @see <a href="https://www.mapbox.com/help/an-open-platform/#tilejson">The 
+ TileJSON specification.</a>
+ */
 @property (nonatomic, readonly, copy) NSURL *URL;
+
+/**
+ The minimum visual size to display tiles for this source. Units in pixels. 
+ Defaults to `512` on each tile side.
+ */
 @property (nonatomic, readonly, assign) NSUInteger tileSize;
+
+/**
+ The tile set used to locate and download tiles. 
+ 
+ A tile set holds the raster tile URL template strings and associated
+ configuration for those strings. It can be passed in place of the URL
+ to TileJSON in order to create a source configured to download tiles
+ from ordinary web URLs.
+ */
 @property (nonatomic, readonly, nullable) MGLTileSet *tileSet;
 
+/**
+ Initializes a source with the given identifier, TileJSON configuration
+ URL, and tile size.
+
+ @param sourceIdentifier A string that uniquely identifies the source.
+ @param url A URL to a TileJSON resource.
+ @param tileSize The minimum visual size to display tiles for the source.
+ */
 - (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier URL:(NSURL *)url tileSize:(CGFloat)tileSize;
 
-- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier tileSize:(CGFloat)tileSize tileSet:(MGLTileSet *)tileSet;
+/**
+ Initializes a source with the given identifier, tile size, and tile 
+ URL template set.
+
+ @param sourceIdentifier A string that uniquely identifies the source.
+ @param tileSet A tile set describing where to download tiles.
+ @param tileSize The minimum visual size to display tiles for the source.
+ */
+- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier tileSet:(MGLTileSet *)tileSet tileSize:(CGFloat)tileSize;
 
 @end
 
diff --git a/platform/darwin/src/MGLRasterSource.mm b/platform/darwin/src/MGLRasterSource.mm
index 06d5a9689c..3d8a11101e 100644
--- a/platform/darwin/src/MGLRasterSource.mm
+++ b/platform/darwin/src/MGLRasterSource.mm
@@ -17,12 +17,12 @@
     return self;
 }
 
-- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier tileSize:(CGFloat)tileSize tileSet:(MGLTileSet *)tileSet;
+- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier tileSet:(MGLTileSet *)tileSet tileSize:(CGFloat)tileSize;
 {
     if (self = [super initWithSourceIdentifier:sourceIdentifier])
     {
-        _tileSize = tileSize;
         _tileSet = tileSet;
+        _tileSize = tileSize;
     }
     return self;
 }
diff --git a/platform/darwin/src/MGLRasterStyleLayer.h b/platform/darwin/src/MGLRasterStyleLayer.h
index b7f2cd7fda..7fdfb04c99 100644
--- a/platform/darwin/src/MGLRasterStyleLayer.h
+++ b/platform/darwin/src/MGLRasterStyleLayer.h
@@ -6,9 +6,14 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ A raster layer which allows customization of styling properties at runtime. You may 
+ instantiate a new raster layer to add to a map style or you may query an 
+ `MGLMapView` for its `style` and obtain existing layers using the 
+ `-[MGLStyle layerWithIdentifier:]` method. 
+ */
 @interface MGLRasterStyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
 
-
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source;
 
 
diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h
index 4d0fd49ea2..bb8f990828 100644
--- a/platform/darwin/src/MGLSource.h
+++ b/platform/darwin/src/MGLSource.h
@@ -1,10 +1,25 @@
 #import <Foundation/Foundation.h>
-#import <CoreGraphics/CoreGraphics.h>
 
+/**
+ A source supplies data to be shown on the map. Sources don't contain styling 
+ details like color or width. Use subclasses of `MGLBaseStyleLayer` to give 
+ visual representation to sources.
+ 
+ You should use the concrete subclasses of `MGLSource` to create vector, 
+ raster, GeoJSON, and other source types.
+ */
 @interface MGLSource : NSObject
 
+/**
+ A string that uniquely identifies the source.
+ */
 @property (nonatomic, copy) NSString *sourceIdentifier;
 
+/**
+ Initializes a source with the given identifier.
+
+ @param sourceIdentifier A string that uniquely identifies the source.
+ */
 - (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier;
 
 @end
diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 585d15c08c..d4972a3d31 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -30,8 +30,9 @@ NS_ASSUME_NONNULL_BEGIN
 static const NSInteger MGLStyleDefaultVersion = 9;
 
 /**
- A collection of convenience methods for creating style URLs of default styles
- provided by Mapbox.
+ The proxy object for the current map style for customization purposes and a 
+ set of convenience methods for creating style URLs of default styles provided 
+ by Mapbox.
  <a href="https://www.mapbox.com/maps/">Learn more about Mapbox default styles</a>.
  */
 @interface MGLStyle : NSObject
diff --git a/platform/darwin/src/MGLStyleLayer.h.ejs b/platform/darwin/src/MGLStyleLayer.h.ejs
index 64a7e06b5f..054adcb32e 100644
--- a/platform/darwin/src/MGLStyleLayer.h.ejs
+++ b/platform/darwin/src/MGLStyleLayer.h.ejs
@@ -33,9 +33,24 @@ typedef NS_ENUM(NSUInteger, MGL<%- camelize(type) %>StyleLayer<%- camelize(prope
 
 <% } -%>
 <% } -%>
+<% if (type == 'background') { -%>
+/**
+ A map style's background layer is the bottommost layer and is used to style a color 
+ or pattern to show below all other map features. You can query an `MGLMapView` for its 
+ `style` and obtain the background layer using the `-[MGLStyle layerWithIdentifier:]` 
+ method and passing `background` for the identifier. 
+ */
+<% } else { -%>
+/**
+ A <%- type %> layer which allows customization of styling properties at runtime. You may 
+ instantiate a new <%- type %> layer to add to a map style or you may query an 
+ `MGLMapView` for its `style` and obtain existing layers using the 
+ `-[MGLStyle layerWithIdentifier:]` method. 
+ */
+<% } -%>
 @interface MGL<%- camelize(type) %>StyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
-
 <% if (type == 'background') { -%>
+
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier;
 <% } -%>
 
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.h b/platform/darwin/src/MGLSymbolStyleLayer.h
index 6b22b6ccfc..c501f512e8 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.h
+++ b/platform/darwin/src/MGLSymbolStyleLayer.h
@@ -70,9 +70,14 @@ typedef NS_ENUM(NSUInteger, MGLSymbolStyleLayerTextTranslateAnchor) {
     MGLSymbolStyleLayerTextTranslateAnchorViewport,
 };
 
+/**
+ A symbol layer which allows customization of styling properties at runtime. You may 
+ instantiate a new symbol layer to add to a map style or you may query an 
+ `MGLMapView` for its `style` and obtain existing layers using the 
+ `-[MGLStyle layerWithIdentifier:]` method. 
+ */
 @interface MGLSymbolStyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
 
-
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source;
 
 - (instancetype)initWithLayerIdentifier:(NSString *)layerIdentifier source:(MGLSource *)source sourceLayer:(NSString *)sourceLayer;
diff --git a/platform/darwin/src/MGLVectorSource.h b/platform/darwin/src/MGLVectorSource.h
index 2402208499..2106a5cf42 100644
--- a/platform/darwin/src/MGLVectorSource.h
+++ b/platform/darwin/src/MGLVectorSource.h
@@ -17,7 +17,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, readonly, nullable) MGLTileSet *tileSet;
 
 /**
- Initializes and returns a vector source from a remote url.
+ Initializes and returns a vector source from a remote URL.
  
  @param sourceIdentifier The source identifier.
  @param URL A remote URL holding the vector source data.
@@ -26,6 +26,13 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier URL:(NSURL *)url;
 
+/**
+ Initializes a source with the given identifier, tile size, and tile
+ URL template set.
+
+ @param sourceIdentifier A string that uniquely identifies the source.
+ @param tileSet A tile set describing where to download tiles.
+ */
 - (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier tileSet:(MGLTileSet *)tileSet;
 
 @end
diff --git a/platform/ios/jazzy.yml b/platform/ios/jazzy.yml
index f1c5d28070..b2b3d3878e 100644
--- a/platform/ios/jazzy.yml
+++ b/platform/ios/jazzy.yml
@@ -51,6 +51,23 @@ custom_categories:
       - MGLPolygonFeature
       - MGLPolylineFeature
       - MGLShapeCollectionFeature
+  - name: Style Layers
+    children:
+      - MGLStyleLayer
+      - MGLBaseStyleLayer
+      - MGLBackgroundStyleLayer
+      - MGLCircleStyleLayer
+      - MGLFillStyleLayer
+      - MGLLineStyleLayer
+      - MGLRasterStyleLayer
+      - MGLSymbolStyleLayer
+  - name: Data Sources
+    children:
+      - MGLSource
+      - MGLGeoJSONSource
+      - MGLRasterSource
+      - MGLTileSet
+      - MGLVectorSource
   - name: Offline Maps
     children:
       - MGLOfflineRegion
diff --git a/platform/macos/jazzy.yml b/platform/macos/jazzy.yml
index af50bb22df..406154ec5e 100644
--- a/platform/macos/jazzy.yml
+++ b/platform/macos/jazzy.yml
@@ -45,6 +45,23 @@ custom_categories:
       - MGLPolygonFeature
       - MGLPolylineFeature
       - MGLShapeCollectionFeature
+  - name: Style Layers
+    children:
+      - MGLStyleLayer
+      - MGLBaseStyleLayer
+      - MGLBackgroundStyleLayer
+      - MGLCircleStyleLayer
+      - MGLFillStyleLayer
+      - MGLLineStyleLayer
+      - MGLRasterStyleLayer
+      - MGLSymbolStyleLayer
+  - name: Data Sources
+    children:
+      - MGLSource
+      - MGLGeoJSONSource
+      - MGLRasterSource
+      - MGLTileSet
+      - MGLVectorSource
   - name: Offline Maps
     children:
       - MGLOfflineRegion