[ios, macos] revised descriptions for abstract classes

9 files changed, 20 insertions, 31 deletions

diff --git a/platform/darwin/src/MGLForegroundStyleLayer.h b/platform/darwin/src/MGLForegroundStyleLayer.h
index 16a973630e..79270d1cc8 100644
--- a/platform/darwin/src/MGLForegroundStyleLayer.h
+++ b/platform/darwin/src/MGLForegroundStyleLayer.h
@@ -11,9 +11,8 @@ 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.
  */
 MGL_EXPORT
 @interface MGLForegroundStyleLayer : MGLStyleLayer
diff --git a/platform/darwin/src/MGLMultiPoint.h b/platform/darwin/src/MGLMultiPoint.h
index 429bbdb22d..e669aff0b0 100644
--- a/platform/darwin/src/MGLMultiPoint.h
+++ b/platform/darwin/src/MGLMultiPoint.h
@@ -10,10 +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
- the method and properties of this class to access information about the
- vertices of the line or polygon.
+ Create instances of `MGLPolyline` or `MGLPolygon` in order to use 
+ properties of `MGLMultiPoint`. You can use the method and properties of this
+ class to access information about the vertices of the line or polygon.
 
  Do not confuse `MGLMultiPoint` with `MGLPointCollection`, which represents a
  collection of related but disconnected points.
diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h
index bd8b6152d2..416d68bf79 100644
--- a/platform/darwin/src/MGLShape.h
+++ b/platform/darwin/src/MGLShape.h
@@ -10,10 +10,9 @@ 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
+ Create instances of `MGLPointAnnotation`, `MGLPointCollection`, `MGLPolyline`,
+ `MGLMultiPolyline`, `MGLPolygon`, `MGLMultiPolygon`, or `MGLShapeCollection` in
+ order to use `MGLShape`'s methods. 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.
diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h
index 8bf48907cc..aea0ec16be 100644
--- a/platform/darwin/src/MGLSource.h
+++ b/platform/darwin/src/MGLSource.h
@@ -16,9 +16,9 @@ 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.
  */
 MGL_EXPORT
 @interface MGLSource : NSObject
diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h
index 7d181667d6..b8524c6827 100644
--- a/platform/darwin/src/MGLStyleLayer.h
+++ b/platform/darwin/src/MGLStyleLayer.h
@@ -14,10 +14,8 @@ 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.
  
  Do not add `MGLStyleLayer` objects to the `style` property of a `MGLMapView` before
  `-mapView:didFinishLoadingStyle:` is called.
diff --git a/platform/darwin/src/MGLStyleValue.h b/platform/darwin/src/MGLStyleValue.h
index 2bb3aca4f4..46943c6624 100644
--- a/platform/darwin/src/MGLStyleValue.h
+++ b/platform/darwin/src/MGLStyleValue.h
@@ -239,11 +239,8 @@ 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.
 
  The `MGLStyleFunction` class takes a generic parameter `T` that indicates the
  Foundation class being wrapped by this class.
diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h
index 538b94037e..96b46f60a2 100644
--- a/platform/darwin/src/MGLTileSource.h
+++ b/platform/darwin/src/MGLTileSource.h
@@ -140,9 +140,8 @@ 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.
  */
 MGL_EXPORT
 @interface MGLTileSource : MGLSource
diff --git a/platform/darwin/src/MGLVectorStyleLayer.h b/platform/darwin/src/MGLVectorStyleLayer.h
index c6193e6046..9535777b24 100644
--- a/platform/darwin/src/MGLVectorStyleLayer.h
+++ b/platform/darwin/src/MGLVectorStyleLayer.h
@@ -9,10 +9,8 @@ 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.
  */
 MGL_EXPORT
 @interface MGLVectorStyleLayer : MGLForegroundStyleLayer
diff --git a/platform/ios/src/MGLUserLocation.h b/platform/ios/src/MGLUserLocation.h
index c41c3ee7fd..30bfc592ca 100644
--- a/platform/ios/src/MGLUserLocation.h
+++ b/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>