From f2c0add19ac6f517ef7796be048b0db4d6262b9e Mon Sep 17 00:00:00 2001 From: jmkiley Date: Tue, 23 May 2017 17:55:38 -0700 Subject: [PATCH 1/6] [ios, macos] revised descriptions for abstract classes --- platform/darwin/src/MGLForegroundStyleLayer.h | 5 ++--- platform/darwin/src/MGLMultiPoint.h | 7 +++---- platform/darwin/src/MGLShape.h | 7 +++---- platform/darwin/src/MGLSource.h | 6 +++--- platform/darwin/src/MGLStyleLayer.h | 6 ++---- platform/darwin/src/MGLStyleValue.h | 7 ++----- platform/darwin/src/MGLTileSource.h | 5 ++--- platform/darwin/src/MGLVectorStyleLayer.h | 6 ++---- platform/ios/src/MGLUserLocation.h | 2 +- 9 files changed, 20 insertions(+), 31 deletions(-) diff --git a/platform/darwin/src/MGLForegroundStyleLayer.h b/platform/darwin/src/MGLForegroundStyleLayer.h index 16a973630e8..79270d1cc87 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 429bbdb22d7..e669aff0b02 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 bd8b6152d2d..416d68bf799 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 Geometry 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 8bf48907cc0..aea0ec16be3 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 7d181667d60..b8524c68276 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 2bb3aca4f4a..46943c66241 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 538b94037ee..96b46f60a28 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 Mapbox Studio’s Tilesets editor. - 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 c6193e60463..9535777b244 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 c41c3ee7fd5..30bfc592cab 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 From a2a4222f7bac4300867f28221ac0a5b67a708702 Mon Sep 17 00:00:00 2001 From: jmkiley Date: Tue, 13 Jun 2017 16:55:59 -0700 Subject: [PATCH 2/6] [ios, macos]revisions round 1 --- platform/darwin/src/MGLForegroundStyleLayer.h | 2 ++ platform/darwin/src/MGLMultiPoint.h | 5 +++-- platform/darwin/src/MGLShape.h | 4 ++-- platform/darwin/src/MGLStyleValue.h | 3 ++- platform/darwin/src/MGLVectorStyleLayer.h | 3 ++- 5 files changed, 11 insertions(+), 6 deletions(-) diff --git a/platform/darwin/src/MGLForegroundStyleLayer.h b/platform/darwin/src/MGLForegroundStyleLayer.h index 79270d1cc87..deeb7051f92 100644 --- a/platform/darwin/src/MGLForegroundStyleLayer.h +++ b/platform/darwin/src/MGLForegroundStyleLayer.h @@ -13,6 +13,8 @@ NS_ASSUME_NONNULL_BEGIN Create instances of `MGLRasterStyleLayer` and the concrete subclasses of `MGLVectorStyleLayer` in order to use `MGLForegroundStyleLayer`'s methods. + Do not create instances of this class directly, and do not create your own + subclasses of this class. */ MGL_EXPORT @interface MGLForegroundStyleLayer : MGLStyleLayer diff --git a/platform/darwin/src/MGLMultiPoint.h b/platform/darwin/src/MGLMultiPoint.h index e669aff0b02..9b089ef8c1c 100644 --- a/platform/darwin/src/MGLMultiPoint.h +++ b/platform/darwin/src/MGLMultiPoint.h @@ -11,8 +11,9 @@ NS_ASSUME_NONNULL_BEGIN composed of multiple vertices. 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. + properties of `MGLMultiPoint`. Do not create instances of `MGLMultiPoint` + directly. 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 416d68bf799..f0de4abaa62 100644 --- a/platform/darwin/src/MGLShape.h +++ b/platform/darwin/src/MGLShape.h @@ -12,8 +12,8 @@ NS_ASSUME_NONNULL_BEGIN Create instances of `MGLPointAnnotation`, `MGLPointCollection`, `MGLPolyline`, `MGLMultiPolyline`, `MGLPolygon`, `MGLMultiPolygon`, or `MGLShapeCollection` in - order to use `MGLShape`'s methods. The shape classes correspond to the - Geometry object + order to use `MGLShape`'s methods. Do not create instances of `MGLShape` directly. + The shape classes correspond to the Geometry object types in the GeoJSON standard, but some have nonstandard names for backwards compatibility. diff --git a/platform/darwin/src/MGLStyleValue.h b/platform/darwin/src/MGLStyleValue.h index 46943c66241..57bd562cb61 100644 --- a/platform/darwin/src/MGLStyleValue.h +++ b/platform/darwin/src/MGLStyleValue.h @@ -240,7 +240,8 @@ MGL_EXPORT `MGLCompositeStyleFunction` object. Create instances of `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, and - `MGLCompositeStyleFunction` in order to use `MGLStyleFunction`'s methods. + `MGLCompositeStyleFunction` in order to use `MGLStyleFunction`'s methods. Do + not create instances of `MGLStyleFunction` directly. The `MGLStyleFunction` class takes a generic parameter `T` that indicates the Foundation class being wrapped by this class. diff --git a/platform/darwin/src/MGLVectorStyleLayer.h b/platform/darwin/src/MGLVectorStyleLayer.h index 9535777b244..fbf39e4b475 100644 --- a/platform/darwin/src/MGLVectorStyleLayer.h +++ b/platform/darwin/src/MGLVectorStyleLayer.h @@ -10,7 +10,8 @@ NS_ASSUME_NONNULL_BEGIN is defined by an `MGLShapeSource` or `MGLVectorSource` object. Create instances of `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLLineStyleLayer`, - and `MGLSymbolStyleLayer` in order to use `MGLVectorStyleLayer`'s properties and methods. + and `MGLSymbolStyleLayer` in order to use `MGLVectorStyleLayer`'s properties and + methods. Do not create instances of `MGLVectorStyleLayer` directly. */ MGL_EXPORT @interface MGLVectorStyleLayer : MGLForegroundStyleLayer From 37e1710adbf8854d0dc20749265845c21d9db7a7 Mon Sep 17 00:00:00 2001 From: jmkiley Date: Tue, 13 Jun 2017 17:04:07 -0700 Subject: [PATCH 3/6] [ios, macos] revisions part 2 --- platform/darwin/src/MGLSource.h | 3 ++- platform/darwin/src/MGLStyleLayer.h | 1 + platform/darwin/src/MGLTileSource.h | 3 ++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h index aea0ec16be3..b79ac9f50d2 100644 --- a/platform/darwin/src/MGLSource.h +++ b/platform/darwin/src/MGLSource.h @@ -18,7 +18,8 @@ NS_ASSUME_NONNULL_BEGIN Create instances of `MGLShapeSource` and the concrete subclasses of `MGLTileSource`, `MGLVectorSource` and `MGLRasterSource` in order to use - `MGLMultiPoint`'s properties and methods. + `MGLMultiPoint`'s properties and methods. Do not create instances of `MGLSource` + directly. */ MGL_EXPORT @interface MGLSource : NSObject diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h index b8524c68276..3be5eec1e5b 100644 --- a/platform/darwin/src/MGLStyleLayer.h +++ b/platform/darwin/src/MGLStyleLayer.h @@ -16,6 +16,7 @@ NS_ASSUME_NONNULL_BEGIN 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. 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 96b46f60a28..d3a109e488a 100644 --- a/platform/darwin/src/MGLTileSource.h +++ b/platform/darwin/src/MGLTileSource.h @@ -141,7 +141,8 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) { Mapbox Studio’s Tilesets editor. Create instances of `MGLRasterSource` and `MGLVectorSource` in order to use - `MGLTileSource`'s properties and methods. + `MGLTileSource`'s properties and methods. Do not create instances of `MGLTileSource` + directly. */ MGL_EXPORT @interface MGLTileSource : MGLSource From b9a9df74c8ad8a4d3366dd129f78976ed90b8517 Mon Sep 17 00:00:00 2001 From: jmkiley Date: Tue, 13 Jun 2017 17:08:29 -0700 Subject: [PATCH 4/6] [ios, macos] revised MGLForegroundStyleLayer --- platform/darwin/src/MGLForegroundStyleLayer.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform/darwin/src/MGLForegroundStyleLayer.h b/platform/darwin/src/MGLForegroundStyleLayer.h index deeb7051f92..bcd323fb99f 100644 --- a/platform/darwin/src/MGLForegroundStyleLayer.h +++ b/platform/darwin/src/MGLForegroundStyleLayer.h @@ -13,8 +13,8 @@ NS_ASSUME_NONNULL_BEGIN Create instances of `MGLRasterStyleLayer` and the concrete subclasses of `MGLVectorStyleLayer` in order to use `MGLForegroundStyleLayer`'s methods. - Do not create instances of this class directly, and do not create your own - subclasses of this class. + Do not create instances of `MGLForegroundStyleLayer` directly, and do not + create your own subclasses of this class. */ MGL_EXPORT @interface MGLForegroundStyleLayer : MGLStyleLayer From ff784d3de2da156b923ac31312f5488d8023edf9 Mon Sep 17 00:00:00 2001 From: jmkiley Date: Wed, 14 Jun 2017 10:28:28 -0700 Subject: [PATCH 5/6] [ios, macos] added subclass warnings --- platform/darwin/src/MGLSource.h | 2 +- platform/darwin/src/MGLStyleLayer.h | 3 ++- platform/darwin/src/MGLStyleValue.h | 3 ++- platform/darwin/src/MGLTileSource.h | 2 +- platform/darwin/src/MGLVectorStyleLayer.h | 3 ++- 5 files changed, 8 insertions(+), 5 deletions(-) diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h index b79ac9f50d2..151363104ec 100644 --- a/platform/darwin/src/MGLSource.h +++ b/platform/darwin/src/MGLSource.h @@ -19,7 +19,7 @@ NS_ASSUME_NONNULL_BEGIN 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. + directly, and do not create your own subclasses of this class. */ MGL_EXPORT @interface MGLSource : NSObject diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h index 3be5eec1e5b..b610a276076 100644 --- a/platform/darwin/src/MGLStyleLayer.h +++ b/platform/darwin/src/MGLStyleLayer.h @@ -16,7 +16,8 @@ NS_ASSUME_NONNULL_BEGIN 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. + 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. diff --git a/platform/darwin/src/MGLStyleValue.h b/platform/darwin/src/MGLStyleValue.h index 57bd562cb61..9c9b1dc4d10 100644 --- a/platform/darwin/src/MGLStyleValue.h +++ b/platform/darwin/src/MGLStyleValue.h @@ -241,7 +241,8 @@ MGL_EXPORT Create instances of `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, and `MGLCompositeStyleFunction` in order to use `MGLStyleFunction`'s methods. Do - not create instances of `MGLStyleFunction` directly. + 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. diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h index d3a109e488a..caeafcd2f6c 100644 --- a/platform/darwin/src/MGLTileSource.h +++ b/platform/darwin/src/MGLTileSource.h @@ -142,7 +142,7 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) { Create instances of `MGLRasterSource` and `MGLVectorSource` in order to use `MGLTileSource`'s properties and methods. Do not create instances of `MGLTileSource` - directly. + directly, and do not create your own subclasses of this class. */ MGL_EXPORT @interface MGLTileSource : MGLSource diff --git a/platform/darwin/src/MGLVectorStyleLayer.h b/platform/darwin/src/MGLVectorStyleLayer.h index fbf39e4b475..e54a580aede 100644 --- a/platform/darwin/src/MGLVectorStyleLayer.h +++ b/platform/darwin/src/MGLVectorStyleLayer.h @@ -11,7 +11,8 @@ NS_ASSUME_NONNULL_BEGIN Create instances of `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLLineStyleLayer`, and `MGLSymbolStyleLayer` in order to use `MGLVectorStyleLayer`'s properties and - methods. Do not create instances of `MGLVectorStyleLayer` directly. + methods. Do not create instances of `MGLVectorStyleLayer` directly, and do not + create your own subclasses of this class. */ MGL_EXPORT @interface MGLVectorStyleLayer : MGLForegroundStyleLayer From 60fc2a25a27b3cde7a2fff2785ab7a41f3a26dc5 Mon Sep 17 00:00:00 2001 From: jmkiley Date: Wed, 14 Jun 2017 10:32:42 -0700 Subject: [PATCH 6/6] [ios, macos] added subclass warnings --- platform/darwin/src/MGLMultiPoint.h | 5 +++-- platform/darwin/src/MGLShape.h | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/platform/darwin/src/MGLMultiPoint.h b/platform/darwin/src/MGLMultiPoint.h index 9b089ef8c1c..ee9eb530a47 100644 --- a/platform/darwin/src/MGLMultiPoint.h +++ b/platform/darwin/src/MGLMultiPoint.h @@ -12,8 +12,9 @@ NS_ASSUME_NONNULL_BEGIN Create instances of `MGLPolyline` or `MGLPolygon` in order to use properties of `MGLMultiPoint`. Do not create instances of `MGLMultiPoint` - directly. You can use the method and properties of this class to access - information about the vertices of the line or polygon. + 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. 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 f0de4abaa62..e9657105521 100644 --- a/platform/darwin/src/MGLShape.h +++ b/platform/darwin/src/MGLShape.h @@ -12,8 +12,9 @@ NS_ASSUME_NONNULL_BEGIN 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. - The shape classes correspond to the Geometry object + 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 Geometry object types in the GeoJSON standard, but some have nonstandard names for backwards compatibility.