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

diff --git a/platform/darwin/src/MGLPointCollection.h b/platform/darwin/src/MGLPointCollection.h
index 95af9dae5e..9e14161aed 100644
--- a/platform/darwin/src/MGLPointCollection.h
+++ b/platform/darwin/src/MGLPointCollection.h
@@ -5,15 +5,26 @@
 #import "MGLShape.h"
 
 /**
- The `MGLPointCollection` class is used to define an array of disconnected 
- coordinates. The points in the collection may be related but are not 
- connected visually in any way.
+ An `MGLPointCollection` object represents a shape consisting of one or more
+ disconnected vertices, specified as `CLLocationCoordinate2D` instances. The
+ points in the collection may be related but are not connected spatially. For
+ example, you could use a point collection to represent all the trees in an
+ orchard.
  
- @note `MGLPointCollection` objects cannot be added to a map view using
- `-[MGLMapView addAnnotations:]` and related methods. However, when used in a
- `MGLPointCollectionFeature` to initialize a `MGLShapeSource` that is added
- to the map view's style, the point collection represents as a group of distinct 
- annotations.
+ You can add point collections to the map by adding them to an `MGLShapeSource`
+ object. Configure the appearance of an `MGLShapeSource`’s or
+ `MGLVectorSource`’s point collections collectively using an
+ `MGLCircleStyleLayer` or `MGLSymbolStyleLayer` object.
+ 
+ You cannot add an `MGLPointCollection` object directly to a map view as an
+ annotation. However, you can create individual `MGLPointAnnotation` objects
+ from the `coordinates` array and add those annotation objects to the map view
+ using the `-[MGLMapView addAnnotations:]` method.
+ 
+ A point collection is known as a
+ <a href="https://tools.ietf.org/html/rfc7946#section-3.1.3">MultiPoint</a>
+ geometry in GeoJSON. Do not confuse `MGLPointCollection` with `MGLMultiPoint`,
+ the abstract superclass of `MGLPolyline` and `MGLPolygon`.
  */
 @interface MGLPointCollection : MGLShape <MGLOverlay>