[ios, macos] Revised descriptions for abstract classes (#9095)

Addresses https://github.com/mapbox/mapbox-gl-native/issues/8635

platform/darwin/src/MGLForegroundStyleLayer.h

@@ -11,9 +11,10 @@ NS_ASSUME_NONNULL_BEGIN
  `MGLForegroundStyleLayer` is an abstract superclass for style layers whose
  content is defined by an `MGLSource` object.
 
- Do not create instances of this class directly, and do not create your own
- subclasses of this class. Instead, create instances of `MGLRasterStyleLayer`
- and the concrete subclasses of `MGLVectorStyleLayer`.
+ Create instances of `MGLRasterStyleLayer` and the concrete subclasses of
+ `MGLVectorStyleLayer` in order to use `MGLForegroundStyleLayer`'s methods.
+ Do not create instances of `MGLForegroundStyleLayer` directly, and do not
+ create your own subclasses of this class.
  */
 MGL_EXPORT
 @interface MGLForegroundStyleLayer : MGLStyleLayer

platform/darwin/src/MGLMultiPoint.h

@@ -10,8 +10,9 @@ NS_ASSUME_NONNULL_BEGIN
  The `MGLMultiPoint` class is an abstract superclass used to define shapes
  composed of multiple vertices.
 
- You do not create instances of this class directly. Instead, you create
- instances of the `MGLPolyline` or `MGLPolygon` classes. However, you can use
+ Create instances of `MGLPolyline` or `MGLPolygon` in order to use 
+ properties of `MGLMultiPoint`. Do not create instances of `MGLMultiPoint`
+ directly and do not create your own subclasses of this class. You can use
  the method and properties of this class to access information about the
  vertices of the line or polygon.
 

platform/darwin/src/MGLShape.h

@@ -10,11 +10,11 @@ NS_ASSUME_NONNULL_BEGIN
  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
+ Create instances of `MGLPointAnnotation`, `MGLPointCollection`, `MGLPolyline`,
+ `MGLMultiPolyline`, `MGLPolygon`, `MGLMultiPolygon`, or `MGLShapeCollection` in
+ order to use `MGLShape`'s methods. Do not create instances of `MGLShape` directly,
+ and do not create your own subclasses of this class. 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.
 

platform/darwin/src/MGLSource.h

@@ -16,9 +16,10 @@ NS_ASSUME_NONNULL_BEGIN
  add and remove sources dynamically using methods such as
  `-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.
 
- Do not create instances of this class directly, and do not create your own
- subclasses of this class. Instead, create instances of `MGLShapeSource` and the
- concrete subclasses of `MGLTileSource`, `MGLVectorSource` and `MGLRasterSource`.
+ Create instances of `MGLShapeSource` and the concrete subclasses of
+ `MGLTileSource`, `MGLVectorSource` and `MGLRasterSource` in order to use
+ `MGLMultiPoint`'s properties and methods. Do not create instances of `MGLSource`
+ directly, and do not create your own subclasses of this class.
  */
 MGL_EXPORT
 @interface MGLSource : NSObject

platform/darwin/src/MGLStyleLayer.h

@@ -14,10 +14,10 @@ NS_ASSUME_NONNULL_BEGIN
  `MGLStyleLayer` object, which you can use to refine the map’s appearance. You
  can also add and remove style layers dynamically.
 
- Do not create instances of this class directly, and do not create your own
- subclasses of this class. Instead, create instances of
- `MGLBackgroundStyleLayer` and the concrete subclasses of
- `MGLForegroundStyleLayer`.
+ Create instances of `MGLBackgroundStyleLayer` and the concrete subclasses of
+ `MGLForegroundStyleLayer` in order to use `MGLStyleLayer`'s properties and methods.
+ You do not create instances of `MGLStyleLayer` directly, and do not
+ create your own subclasses of this class.
  
  Do not add `MGLStyleLayer` objects to the `style` property of a `MGLMapView` before
  `-mapView:didFinishLoadingStyle:` is called.

platform/darwin/src/MGLStyleValue.h

@@ -239,11 +239,10 @@ MGL_EXPORT
  defined by an `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, or
  `MGLCompositeStyleFunction` object.
  
- Do not create instances of this class directly, and do not create your own
- subclasses of this class. Instead, use one of the class factory methods in
- `MGLStyleValue` to create instances of the following concrete subclasses:
- `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, and
- `MGLCompositeStyleFunction`.
+ Create instances of `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, and
+ `MGLCompositeStyleFunction` in order to use `MGLStyleFunction`'s methods. Do
+ not create instances of `MGLStyleFunction` directly, and do not create your
+ own subclasses of this class.
 
  The `MGLStyleFunction` class takes a generic parameter `T` that indicates the
  Foundation class being wrapped by this class.

platform/darwin/src/MGLTileSource.h

@@ -140,9 +140,9 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) {
  Mapbox-hosted tile set, view it in
  <a href="https://www.mapbox.com/studio/tilesets/">Mapbox Studio’s Tilesets editor</a>.
 
- Do not create instances of this class directly, and do not create your own
- subclasses of this class. Instead, create instances of `MGLRasterSource` and
- `MGLVectorSource`.
+ Create instances of `MGLRasterSource` and `MGLVectorSource` in order to use
+ `MGLTileSource`'s properties and methods. Do not create instances of `MGLTileSource`
+ directly, and do not create your own subclasses of this class.
  */
 MGL_EXPORT
 @interface MGLTileSource : MGLSource

platform/darwin/src/MGLVectorStyleLayer.h

@@ -9,10 +9,10 @@ NS_ASSUME_NONNULL_BEGIN
  `MGLVectorStyleLayer` is an abstract superclass for style layers whose content
  is defined by an `MGLShapeSource` or `MGLVectorSource` object.
 
- Do not create instances of this class directly, and do not create your own
- subclasses of this class. Instead, create instances of the following concrete
- subclasses: `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLLineStyleLayer`,
- and `MGLSymbolStyleLayer`.
+ Create instances of `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLLineStyleLayer`,
+ and `MGLSymbolStyleLayer` in order to use `MGLVectorStyleLayer`'s properties and
+ methods. Do not create instances of `MGLVectorStyleLayer` directly, and do not
+ create your own subclasses of this class.
  */
 MGL_EXPORT
 @interface MGLVectorStyleLayer : MGLForegroundStyleLayer

platform/ios/src/MGLUserLocation.h

@@ -8,7 +8,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  The MGLUserLocation class defines a specific type of annotation that identifies
  the user’s current location. You do not create instances of this class
- directly. Instead, you retrieve an existing MGLUserLocation object from the
+ directly. Instead, you retrieve an existing `MGLUserLocation` object from the
  `userLocation` property of the map view displayed in your application.
  */
 @interface MGLUserLocation : NSObject <MGLAnnotation, NSSecureCoding>