[ios, macos] revised some warnings in abstract classesupstream/jmkiley-update-initializer-docs

5 files changed, 12 insertions, 17 deletions

diff --git a/platform/darwin/src/MGLForegroundStyleLayer.h b/platform/darwin/src/MGLForegroundStyleLayer.h
index 16a973630e..2bb0dd6829 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 `MGLRasterStyleLayer` and the concrete subclasses of `MGLVectorStyleLayer`
+ in order to use `MGLForegroundStyleLayer` methods.
  */
 MGL_EXPORT
 @interface MGLForegroundStyleLayer : MGLStyleLayer
diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h
index 8bf48907cc..f0c41ccf1a 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`.
+ You can create instances of `MGLShapeSource` and the concrete subclasses of
+ `MGLTileSource`, `MGLVectorSource` and `MGLRasterSource`, rather than creating
+ instances of `MGLShapeSource` directly.
  */
 MGL_EXPORT
 @interface MGLSource : NSObject
diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h
index d68aee29bc..5966350ab1 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` properties.
  
  Do not add `MGLStyleLayer` objects to the `style` property of a `MGLMapView` before
  `-mapView:didFinishLoadingStyle:` is called.
diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h
index 538b94037e..a0cb850eb3 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` methods.
  */
 MGL_EXPORT
 @interface MGLTileSource : MGLSource
diff --git a/platform/darwin/src/MGLVectorStyleLayer.h b/platform/darwin/src/MGLVectorStyleLayer.h
index c6193e6046..1cdc55665a 100644
--- a/platform/darwin/src/MGLVectorStyleLayer.h
+++ b/platform/darwin/src/MGLVectorStyleLayer.h
@@ -9,10 +9,9 @@ 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`.
+ You can use `MGLVectorStyleLayer` properties by creating instances of the
+ following concrete subclasses: `MGLCircleStyleLayer`, `MGLFillStyleLayer`,
+ `MGLLineStyleLayer`, and `MGLSymbolStyleLayer`.
  */
 MGL_EXPORT
 @interface MGLVectorStyleLayer : MGLForegroundStyleLayer