[ios, macos] Reorganized MGLStyle

2 files changed, 95 insertions, 77 deletions

diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 7f01c230c5..96dc8fba49 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -37,7 +37,7 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  */
 @interface MGLStyle : NSObject
 
-#pragma mark Default Style URLs
+#pragma mark Accessing Common Styles
 
 /**
  Returns the URL to version 8 of the
@@ -165,6 +165,8 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  */
 + (NSURL *)satelliteStreetsStyleURLWithVersion:(NSInteger)version;
 
+#pragma mark Accessing Metadata About the Style
+
 /**
  The name of the style.
 
@@ -172,25 +174,40 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  */
 @property (readonly, copy, nullable) NSString *name;
 
-#pragma mark Runtime Styling
+#pragma mark Managing Sources
 
 /**
- Returns a layer that conforms to `MGLStyleLayer` if any layer with the given
- identifier was found.
+ Returns a source with the given identifier in the current style.
 
- @return An instance of a concrete subclass of `MGLStyleLayer` associated with
-    the given identifier.
+ @return An instance of a concrete subclass of `MGLSource` associated with the
+    given identifier, or `nil` if the current style contains no such source.
  */
-- (nullable MGLStyleLayer *)layerWithIdentifier:(NSString *)identifier;
+- (nullable MGLSource *)sourceWithIdentifier:(NSString *)identifier;
 
+/**
+ Adds a new source to the current style.
+ 
+ @param source The source to add to the current style.
+ */
+- (void)addSource:(MGLSource *)source;
 
 /**
- Returns a source if any source with the given identifier was found.
+ Removes a source from the current style.
+ 
+ @param source The source to remove from the current style.
+ */
+- (void)removeSource:(MGLSource *)source;
 
- @return An instance of a concrete subclass of `MGLSource` associated with the
-    given identifier.
+#pragma mark Managing Style Layers
+
+/**
+ Returns a style layer with the given identifier in the current style.
+ 
+ @return An instance of a concrete subclass of `MGLStyleLayer` associated with
+    the given identifier, or `nil` if the current style contains no such style
+    layer.
  */
-- (nullable MGLSource *)sourceWithIdentifier:(NSString *)identifier;
+- (nullable MGLStyleLayer *)layerWithIdentifier:(NSString *)identifier;
 
 /**
  Adds a new layer on top of existing layers.
@@ -216,19 +233,7 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  */
 - (void)removeLayer:(MGLStyleLayer *)layer;
 
-/**
- Adds a new source to the map view.
-
- @param source The source to add to the map view.
- */
-- (void)addSource:(MGLSource *)source;
-
-/**
- Removes a source from the map view.
-
- @param source The source to remove.
- */
-- (void)removeSource:(MGLSource *)source;
+#pragma mark Managing Style Classes
 
 /**
  Currently active style classes, represented as an array of string identifiers.
@@ -258,12 +263,14 @@ static const NSInteger MGLStyleDefaultVersion = 9;
  */
 - (void)removeStyleClass:(NSString *)styleClass;
 
-/**
-Adds or overrides an image used by the style’s layers.
-
-To use an image in a style layer, give it a unique name using this method,
-then set the `iconImage` property of an `MGLSymbolStyleLayer` object to that name.
+#pragma mark Managing a Style’s Images
 
+/**
+ Adds or overrides an image used by the style’s layers.
+ 
+ To use an image in a style layer, give it a unique name using this method, then
+ set the `iconImage` property of an `MGLSymbolStyleLayer` object to that name.
+ 
  @param image The image for the name.
  @param name The name of the image to set to the style.
  */
diff --git a/platform/darwin/src/MGLStyle.mm b/platform/darwin/src/MGLStyle.mm
index 980abe3e3d..69d76614c0 100644
--- a/platform/darwin/src/MGLStyle.mm
+++ b/platform/darwin/src/MGLStyle.mm
@@ -46,6 +46,8 @@
 
 @implementation MGLStyle
 
+#pragma mark Default style URLs
+
 static_assert(mbgl::util::default_styles::currentVersion == MGLStyleDefaultVersion, "mbgl::util::default_styles::currentVersion and MGLStyleDefaultVersion disagree.");
 
 /// @param name The style’s marketing name, written in lower camelCase.
@@ -96,6 +98,8 @@ static NSURL *MGLStyleURL_emerald;
     return MGLStyleURL_emerald;
 }
 
+#pragma mark Metadata
+
 - (NSString *)name {
     return @(self.mapView.mbglMap->getStyleName().c_str());
 }
@@ -104,6 +108,58 @@ static NSURL *MGLStyleURL_emerald;
     return [NSURL URLWithString:@(self.mapView.mbglMap->getStyleURL().c_str())];
 }
 
+#pragma mark Sources
+
+- (MGLSource *)sourceWithIdentifier:(NSString *)identifier
+{
+    auto mbglSource = self.mapView.mbglMap->getSource(identifier.UTF8String);
+    if (!mbglSource) {
+        return nil;
+    }
+
+    // TODO: Fill in options specific to the respective source classes
+    // https://github.com/mapbox/mapbox-gl-native/issues/6584
+    MGLSource *source;
+    if (mbglSource->is<mbgl::style::VectorSource>()) {
+        source = [[MGLVectorSource alloc] initWithIdentifier:identifier];
+    } else if (mbglSource->is<mbgl::style::GeoJSONSource>()) {
+        source = [[MGLGeoJSONSource alloc] initWithIdentifier:identifier];
+    } else if (mbglSource->is<mbgl::style::RasterSource>()) {
+        source = [[MGLRasterSource alloc] initWithIdentifier:identifier];
+    } else {
+        NSAssert(NO, @"Unrecognized source type");
+        return nil;
+    }
+    
+    source.rawSource = mbglSource;
+
+    return source;
+}
+
+- (void)addSource:(MGLSource *)source
+{
+    if (!source.rawSource) {
+        [NSException raise:NSInvalidArgumentException format:
+         @"The source %@ cannot be added to the style. "
+         @"Make sure the source was created as a member of a concrete subclass of MGLSource.",
+         source];
+    }
+    [source addToMapView:self.mapView];
+}
+
+- (void)removeSource:(MGLSource *)source
+{
+    if (!source.rawSource) {
+        [NSException raise:NSInvalidArgumentException format:
+         @"The source %@ cannot be removed from the style. "
+         @"Make sure the source was created as a member of a concrete subclass of MGLSource.",
+         source];
+    }
+    [source removeFromMapView:self.mapView];
+}
+
+#pragma mark Style layers
+
 - (MGLStyleLayer *)layerWithIdentifier:(NSString *)identifier
 {
     auto mbglLayer = self.mapView.mbglMap->getLayer(identifier.UTF8String);
@@ -139,33 +195,6 @@ static NSURL *MGLStyleURL_emerald;
     return styleLayer;
 }
 
-- (MGLSource *)sourceWithIdentifier:(NSString *)identifier
-{
-    auto mbglSource = self.mapView.mbglMap->getSource(identifier.UTF8String);
-    
-    if (!mbglSource) {
-        return nil;
-    }
-
-    // TODO: Fill in options specific to the respective source classes
-    // https://github.com/mapbox/mapbox-gl-native/issues/6584
-    MGLSource *source;
-    if (mbglSource->is<mbgl::style::VectorSource>()) {
-        source = [[MGLVectorSource alloc] initWithIdentifier:identifier];
-    } else if (mbglSource->is<mbgl::style::GeoJSONSource>()) {
-        source = [[MGLGeoJSONSource alloc] initWithIdentifier:identifier];
-    } else if (mbglSource->is<mbgl::style::RasterSource>()) {
-        source = [[MGLRasterSource alloc] initWithIdentifier:identifier];
-    } else {
-        NSAssert(NO, @"Unrecognized source type");
-        return nil;
-    }
-    
-    source.rawSource = mbglSource;
-
-    return source;
-}
-
 - (void)removeLayer:(MGLStyleLayer *)layer
 {
     if (!layer.rawLayer) {
@@ -207,27 +236,7 @@ static NSURL *MGLStyleURL_emerald;
     [layer addToMapView:self.mapView belowLayer:otherLayer];
 }
 
-- (void)addSource:(MGLSource *)source
-{
-    if (!source.rawSource) {
-        [NSException raise:NSInvalidArgumentException format:
-         @"The source %@ cannot be added to the style. "
-         @"Make sure the source was created as a member of a concrete subclass of MGLSource.",
-         source];
-    }
-    [source addToMapView:self.mapView];
-}
-
-- (void)removeSource:(MGLSource *)source
-{
-    if (!source.rawSource) {
-        [NSException raise:NSInvalidArgumentException format:
-         @"The source %@ cannot be removed from the style. "
-         @"Make sure the source was created as a member of a concrete subclass of MGLSource.",
-         source];
-    }
-    [source removeFromMapView:self.mapView];
-}
+#pragma mark Style classes
 
 - (NS_ARRAY_OF(NSString *) *)styleClasses
 {
@@ -282,6 +291,8 @@ static NSURL *MGLStyleURL_emerald;
     }
 }
 
+#pragma mark Style images
+
 - (void)setImage:(MGLImage *)image forName:(NSString *)name
 {
     NSAssert(image, @"image is null");