[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, 33 insertions, 8 deletions

diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h
index af815da0e9..ecb66118a1 100644
--- a/platform/darwin/src/MGLShape.h
+++ b/platform/darwin/src/MGLShape.h
@@ -5,11 +5,23 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- The `MGLShape` class is an abstract class that defines the basic properties for
- all shape-based annotation objects. This class must be subclassed and cannot be
- used as is. Subclasses are responsible for defining the geometry of the shape
- and providing an appropriate value for the coordinate property inherited from
- the `MGLAnnotation` protocol.
+ `MGLShape` is an abstract class that represents a shape or annotation. Shapes
+ constitute the content of a map – not only the overlays atop the map, but also
+ the content that forms the base map.
+ 
+ You do not create instances of this class directly or create subclasses of this
+ class. Instead, you create instances of `MGLPointAnnotation`, 
+ `MGLPointCollection`, `MGLPolyline`, `MGLMultiPolyline`, `MGLPolygon`,
+ `MGLMultiPolygon`, or `MGLShapeCollection`. The shape classes correspond to the
+ <a href="https://tools.ietf.org/html/rfc7946#section-3.1">Geometry</a> object
+ types in the GeoJSON standard, but some have nonstandard names for backwards
+ compatibility.
+ 
+ You can add shapes to the map by adding them to an `MGLShapeSource` object.
+ Configure the appearance of an `MGLShapeSource`’s or `MGLVectorSource`’s shapes
+ collectively using a concrete instance of `MGLVectorStyleLayer`. Alternatively,
+ you can add some kinds of shapes directly to a map view as annotations or
+ overlays.
  */
 @interface MGLShape : NSObject <MGLAnnotation>
 
@@ -38,21 +50,34 @@ NS_ASSUME_NONNULL_BEGIN
 #pragma mark Accessing the Shape Attributes
 
 /**
- The title of the shape annotation. The default value of this property is `nil`.
+ The title of the shape annotation.
+ 
+ The default value of this property is `nil`.
+ 
+ This property is ignored when the shape is used in an `MGLShapeSource`. To name
+ a shape used in a shape source, create an `MGLFeature` and add an attribute to
+ the `MGLFeature.attributes` property.
  */
 @property (nonatomic, copy, nullable) NSString *title;
 
 /**
  The subtitle of the shape annotation. The default value of this property is
  `nil`.
+ 
+ This property is ignored when the shape is used in an `MGLShapeSource`. To
+ provide additional information about a shape used in a shape source, create an
+ `MGLFeature` and add an attribute to the `MGLFeature.attributes` property.
  */
 @property (nonatomic, copy, nullable) NSString *subtitle;
 
 #if !TARGET_OS_IPHONE
 
 /**
- The tooltip of the shape annotation. The default value of this property is
- `nil`.
+ The tooltip of the shape annotation.
+ 
+ The default value of this property is `nil`.
+ 
+ This property is ignored when the shape is used in an `MGLShapeSource`.
  */
 @property (nonatomic, copy, nullable) NSString *toolTip;