[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

.gitignore

@@ -29,3 +29,4 @@ xcuserdata
 **/token
 /platform/macos/macos.xcworkspace/xcshareddata/macos.xcscmblueprint
 /platform/ios/ios.xcworkspace/xcshareddata/ios.xcscmblueprint
+/documentation

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;

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;
 

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;

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;

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;

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
 

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;
 }

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;
 
 

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

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

platform/darwin/src/MGLStyleLayer.h.ejs

@@ -33,9 +33,24 @@ typedef NS_ENUM(NSUInteger, MGL<%- camelize(type) %>StyleLayer<%- camelize(prope
 
 <% } -%>
 <% } -%>
-@interface MGL<%- camelize(type) %>StyleLayer : MGLBaseStyleLayer <MGLStyleLayer>
-
 <% 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;
 <% } -%>
 

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;

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

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

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