Merge branch 'release-ios-v3.4.0' into 1ec5-release-ios-v3.4.0-beta.7

1 files changed, 46 insertions, 9 deletions

diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h
index cc545d783f..d1c150d02e 100644
--- a/platform/darwin/src/MGLShape.h
+++ b/platform/darwin/src/MGLShape.h
@@ -6,14 +6,30 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- The `MGLShape` class is an abstract class that defines the basic properties for
- all shape-based annotation objects. This class must be subclassed and cannot be
- used as is. Subclasses are responsible for defining the geometry of the shape
- and providing an appropriate value for the coordinate property inherited from
- the `MGLAnnotation` protocol.
+ `MGLShape` is an abstract class that represents a shape or annotation. Shapes
+ 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
+ types in the GeoJSON standard, but some have nonstandard names for backwards
+ compatibility.
+ 
+ Although you do not create instances of this class directly, you can use its
+ `+[MGLShape shapeWithData:encoding:error:]` factory method to create one of the
+ concrete subclasses of `MGLShape` noted above from GeoJSON data.
+ 
+ You can add shapes to the map by adding them to an `MGLShapeSource` object.
+ Configure the appearance of an `MGLShapeSource`’s or `MGLVectorSource`’s shapes
+ collectively using a concrete instance of `MGLVectorStyleLayer`. Alternatively,
+ you can add some kinds of shapes directly to a map view as annotations or
+ overlays.
  */
 MGL_EXPORT
-@interface MGLShape : NSObject <MGLAnnotation>
+@interface MGLShape : NSObject <MGLAnnotation, NSSecureCoding>
 
 #pragma mark Creating a Shape
 
@@ -27,6 +43,14 @@ MGL_EXPORT
  collection object, the returned value is an instance of
  `MGLShapeCollectionFeature`.
  
+ ### Example
+ 
+ ```swift
+ let url = mainBundle.url(forResource: "amsterdam", withExtension: "geojson")!
+ let data = try! Data(contentsOf: url)
+ let feature = try! MGLShape(data: data, encoding: String.Encoding.utf8.rawValue) as! MGLShapeCollectionFeature
+ ```
+ 
  @param data String data containing GeoJSON source code.
  @param encoding The encoding used by `data`.
  @param outError Upon return, if an error has occurred, a pointer to an
@@ -40,21 +64,34 @@ MGL_EXPORT
 #pragma mark Accessing the Shape Attributes
 
 /**
- The title of the shape annotation. The default value of this property is `nil`.
+ The title of the shape annotation.
+ 
+ The default value of this property is `nil`.
+ 
+ This property is ignored when the shape is used in an `MGLShapeSource`. To name
+ a shape used in a shape source, create an `MGLFeature` and add an attribute to
+ the `MGLFeature.attributes` property.
  */
 @property (nonatomic, copy, nullable) NSString *title;
 
 /**
  The subtitle of the shape annotation. The default value of this property is
  `nil`.
+ 
+ This property is ignored when the shape is used in an `MGLShapeSource`. To
+ provide additional information about a shape used in a shape source, create an
+ `MGLFeature` and add an attribute to the `MGLFeature.attributes` property.
  */
 @property (nonatomic, copy, nullable) NSString *subtitle;
 
 #if !TARGET_OS_IPHONE
 
 /**
- The tooltip of the shape annotation. The default value of this property is
- `nil`.
+ The tooltip of the shape annotation.
+ 
+ The default value of this property is `nil`.
+ 
+ This property is ignored when the shape is used in an `MGLShapeSource`.
  */
 @property (nonatomic, copy, nullable) NSString *toolTip;