[ios, macos] Update and reformat documentation for runtime styling (#7475)

* [ios, macos] Optimized changelog for runtime styling

Changelog entries related to style JSON now lead off with the analogous portion of the runtime styling API.

* [ios, macos] Autolink cross-class property references in docs

jazzy can autolink `Class.property` references in documentation comments.

* [ios, macos] Removed extra blank lines

* [ios, macos] Corrected typo in MGLMultiPoint docs

* [ios, macos] Rewrote shape and feature docs

Rewrote documentation about MGLShape, its subclasses, and MGLFeature to emphasize runtime styling uses over annotation uses, associate each type with real-world concepts, cross-reference related style layer classes, and cross-reference related or easily confused shape classes. Links to the GeoJSON specification have been updated to RFC 7946.

* [ios, macos] Expanded style layer docs

With this change, documentation about style layer classes is nominally based on the documentation in the style specification. However, all the existing layer types’ documentation has been overridden to explain what the layer looks like, relate the layer to a real-world concept, and cross-reference related geometry classes. This change also corrects the description of MGLBackgroundStyleLayer, which erroneously stated that the identifier must be “background”, whereas that only happens to be true by default for Studio template styles.

* [ios, macos] Wrap style layer docs

* [ios, macos] Removed unused code

* [ios, macos] Corrected symbol references in docs

* [ios, macos] Corrected typo in abstract class exception

1 files changed, 111 insertions, 48 deletions

diff --git a/platform/darwin/src/MGLLineStyleLayer.h b/platform/darwin/src/MGLLineStyleLayer.h
index c47c7d5166..c0f2eb322b 100644
--- a/platform/darwin/src/MGLLineStyleLayer.h
+++ b/platform/darwin/src/MGLLineStyleLayer.h
@@ -9,19 +9,24 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  The display of line endings.
  
- Values of this type are used in the `lineCap` property of `MGLLineStyleLayer`.
+ Values of this type are used in the `MGLLineStyleLayer.lineCap`
+ property.
  */
 typedef NS_ENUM(NSUInteger, MGLLineCap) {
     /**
-     A cap with a squared-off end which is drawn to the exact endpoint of the line.
+     A cap with a squared-off end which is drawn to the exact endpoint of the
+     line.
      */
     MGLLineCapButt,
     /**
-     A cap with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
+     A cap with a rounded end which is drawn beyond the endpoint of the line at
+     a radius of one-half of the line's width and centered on the endpoint of
+     the line.
      */
     MGLLineCapRound,
     /**
-     A cap with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
+     A cap with a squared-off end which is drawn beyond the endpoint of the line
+     at a distance of one-half of the line's width.
      */
     MGLLineCapSquare,
 };
@@ -29,19 +34,24 @@ typedef NS_ENUM(NSUInteger, MGLLineCap) {
 /**
  The display of lines when joining.
  
- Values of this type are used in the `lineJoin` property of `MGLLineStyleLayer`.
+ Values of this type are used in the `MGLLineStyleLayer.lineJoin`
+ property.
  */
 typedef NS_ENUM(NSUInteger, MGLLineJoin) {
     /**
-     A join with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
+     A join with a squared-off end which is drawn beyond the endpoint of the
+     line at a distance of one-half of the line's width.
      */
     MGLLineJoinBevel,
     /**
-     A join with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
+     A join with a rounded end which is drawn beyond the endpoint of the line at
+     a radius of one-half of the line's width and centered on the endpoint of
+     the line.
      */
     MGLLineJoinRound,
     /**
-     A join with a sharp, angled corner which is drawn with the outer sides beyond the endpoint of the path until they meet.
+     A join with a sharp, angled corner which is drawn with the outer sides
+     beyond the endpoint of the path until they meet.
      */
     MGLLineJoinMiter,
 };
@@ -49,7 +59,8 @@ typedef NS_ENUM(NSUInteger, MGLLineJoin) {
 /**
  Controls the translation reference point.
  
- Values of this type are used in the `lineTranslateAnchor` property of `MGLLineStyleLayer`.
+ Values of this type are used in the `MGLLineStyleLayer.lineTranslateAnchor`
+ property.
  */
 typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
     /**
@@ -63,10 +74,19 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
 };
 
 /**
- 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. 
+ An `MGLLineStyleLayer` is a style layer that renders one or more stroked
+ polylines on the map.
+ 
+ Use a line style layer to configure the visual appearance of polyline or
+ multipolyline features in vector tiles loaded by an `MGLVectorSource` object or
+ `MGLPolyline`, `MGLPolylineFeature`, `MGLMultiPolyline`, or
+ `MGLMultiPolylineFeature` instances in an `MGLShapeSource` object.
+ 
+ You can access an existing line style layer using the
+ `-[MGLStyle layerWithIdentifier:]` method if you know its identifier;
+ otherwise, find it using the `MGLStyle.layers` property. You can also create a
+ new line style layer and add it to the style using a method such as
+ `-[MGLStyle addLayer:]`.
  */
 @interface MGLLineStyleLayer : MGLVectorStyleLayer
 
@@ -75,32 +95,44 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
 /**
  The display of line endings.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineCapButt`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing `MGLLineCapButt`. Set this property to `nil` to
+ reset it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineCap;
 
 /**
  The display of lines when joining.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineJoinMiter`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing `MGLLineJoinMiter`. Set this property to `nil` to
+ reset it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineJoin;
 
 /**
  Used to automatically convert miter joins to bevel joins for sharp angles.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `2`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `2`. Set this property to `nil` to reset
+ it to the default value.
  
- This property is only applied to the style if `lineJoin` is set to an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineJoinMiter`. Otherwise, it is ignored.
+ This property is only applied to the style if `lineJoin` is set to an
+ `MGLStyleValue` object containing an `NSValue` object containing
+ `MGLLineJoinMiter`. Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineMiterLimit;
 
 /**
  Used to automatically convert round joins to miter joins for shallow angles.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `1.05`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `1.05`. Set this property to `nil` to
+ reset it to the default value.
  
- This property is only applied to the style if `lineJoin` is set to an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineJoinRound`. Otherwise, it is ignored.
+ This property is only applied to the style if `lineJoin` is set to an
+ `MGLStyleValue` object containing an `NSValue` object containing
+ `MGLLineJoinRound`. Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineRoundLimit;
 
@@ -108,10 +140,12 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
 
 /**
  Blur applied to the line, in points.
-
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `0`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `0`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineBlur;
 
@@ -119,90 +153,119 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
 /**
  The color with which the line will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing `UIColor.blackColor`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `linePattern` is set to `nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing
+ `UIColor.blackColor`. Set this property to `nil` to reset it to the default
+ value.
+ 
+ This property is only applied to the style if `linePattern` is set to `nil`.
+ Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<MGLColor *> *lineColor;
 #else
 /**
  The color with which the line will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing `NSColor.blackColor`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `linePattern` is set to `nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing
+ `NSColor.blackColor`. Set this property to `nil` to reset it to the default
+ value.
+ 
+ This property is only applied to the style if `linePattern` is set to `nil`.
+ Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<MGLColor *> *lineColor;
 #endif
 
 /**
- Specifies the lengths of the alternating dashes and gaps that form the dash pattern. The lengths are later scaled by the line width. To convert a dash length to points, multiply the length by the current line width.
-
+ Specifies the lengths of the alternating dashes and gaps that form the dash
+ pattern. The lengths are later scaled by the line width. To convert a dash
+ length to points, multiply the length by the current line width.
+ 
  This property is measured in line widths.
-
- This property is only applied to the style if `linePattern` is set to `nil`. Otherwise, it is ignored.
  
- This attribute corresponds to the <a href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-dasharray"><code>line-dasharray</code></a> paint property in the Mapbox Style Specification.
+ This property is only applied to the style if `linePattern` is set to `nil`.
+ Otherwise, it is ignored.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#layout-line-line-dasharray"><code>line-dasharray</code></a>
+ layout property in the Mapbox Style Specification.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSArray<NSNumber *> *> *lineDashPattern;
 
-
 @property (nonatomic, null_resettable) MGLStyleValue<NSArray<NSNumber *> *> *lineDasharray __attribute__((unavailable("Use lineDashPattern instead.")));
 
 /**
- Draws a line casing outside of a line's actual path. Value indicates the width of the inner gap.
-
+ Draws a line casing outside of a line's actual path. Value indicates the width
+ of the inner gap.
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `0`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `0`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineGapWidth;
 
 /**
- The line's offset. For linear features, a positive value offsets the line to the right, relative to the direction of the line, and a negative value to the left. For polygon features, a positive value results in an inset, and a negative value results in an outset.
-
+ The line's offset. For linear features, a positive value offsets the line to
+ the right, relative to the direction of the line, and a negative value to the
+ left. For polygon features, a positive value results in an inset, and a
+ negative value results in an outset.
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `0`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `0`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineOffset;
 
 /**
  The opacity at which the line will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `1`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `1`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineOpacity;
 
 /**
- Name of image in style images to use for drawing image lines. For seamless patterns, image width must be a factor of two (2, 4, 8, ..., 512).
+ Name of image in style images to use for drawing image lines. For seamless
+ patterns, image width must be a factor of two (2, 4, 8, ..., 512).
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSString *> *linePattern;
 
 /**
  The geometry's offset.
-
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing a `CGVector` struct set to 0 points from the left and 0 points from the top. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points from the left
+ and 0 points from the top. Set this property to `nil` to reset it to the
+ default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslate;
 
 /**
  Controls the translation reference point.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineTranslateAnchorMap`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `lineTranslate` is non-`nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing `MGLLineTranslateAnchorMap`. Set this property to
+ `nil` to reset it to the default value.
+ 
+ This property is only applied to the style if `lineTranslate` is non-`nil`.
+ Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslateAnchor;
 
 /**
  Stroke thickness.
-
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `1`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `1`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineWidth;