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

1 files changed, 47 insertions, 11 deletions

diff --git a/platform/darwin/src/MGLPolygon.h b/platform/darwin/src/MGLPolygon.h
index 57402326d5..560741a150 100644
--- a/platform/darwin/src/MGLPolygon.h
+++ b/platform/darwin/src/MGLPolygon.h
@@ -10,10 +10,39 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- The `MGLPolygon` class represents a shape consisting of one or more points that
- define a closed polygon. The points are connected end-to-end in the order they
- are provided. The first and last points are connected to each other to create
- the closed shape.
+ An `MGLPolygon` object represents a closed shape consisting of four or more
+ vertices, specified as `CLLocationCoordinate2D` instances, and the edges that
+ connect them. For example, you could use a polygon shape to represent a
+ building, a lake, or an area you want to highlight.
+ 
+ You can add polygon shapes to the map by adding them to an `MGLShapeSource`
+ object. Configure the appearance of an `MGLShapeSource`’s or
+ `MGLVectorSource`’s polygons collectively using an `MGLFillStyleLayer` or
+ `MGLSymbolStyleLayer` object.
+ 
+ Alternatively, you can add a polygon overlay directly to a map view using the
+ `-[MGLMapView addAnnotation:]` or `-[MGLMapView addOverlay:]` method. Configure
+ a polygon overlay’s appearance using
+ `-[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:]` and
+ `-[MGLMapViewDelegate mapView:fillColorForPolygonAnnotation:]`.
+ 
+ The vertices are automatically connected in the order in which you provide
+ them. You should close the polygon by specifying the same
+ `CLLocationCoordinate2D` as the first and last vertices; otherwise, the
+ polygon’s fill may not cover the area you expect it to. To avoid filling the
+ space within the shape, give the polygon a transparent fill or use an
+ `MGLPolyline` object.
+ 
+ A polygon may have one or more interior polygons, or holes, that you specify as
+ `MGLPolygon` objects with the `+polygonWithCoordinates:count:interiorPolygons:`
+ method. For example, if a polygon represents a lake, it could exclude an island
+ within the lake using an interior polygon. Interior polygons may not themselves
+ have interior polygons. To represent a shape that includes a polygon within a
+ hole or, more generally, to group multiple polygons together in one shape, use
+ an `MGLMultiPolygon` or `MGLShapeCollection` object.
+ 
+ To make the polygon straddle the antimeridian, specify some longitudes less
+ than −180 degrees or greater than 180 degrees.
  */
 MGL_EXPORT
 @interface MGLPolygon : MGLMultiPoint <MGLOverlay>
@@ -57,14 +86,21 @@ MGL_EXPORT
 @end
 
 /**
- The `MGLMultiPolygon` class represents a shape consisting of one or more
- polygons that do not overlap. For example, you would use an `MGLMultiPolygon`
- object to represent an atoll together with an island in the atoll’s lagoon:
- the atoll itself would be one `MGLPolygon` object, while the inner island would
- be another.
+ An `MGLMultiPolygon` object represents a shape consisting of one or more
+ polygons that do not overlap. For example, you could use a multipolygon shape
+ to represent the body of land that consists of an island surrounded by an
+ atoll: the inner island would be one `MGLPolygon` object, while the surrounding
+ atoll would be another. You could also use a multipolygon shape to represent a
+ group of disconnected but related buildings.
+ 
+ You can add multipolygon shapes to the map by adding them to an
+ `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or
+ `MGLVectorSource`’s multipolygons collectively using an `MGLFillStyleLayer` or
+ `MGLSymbolStyleLayer` object.
  
- @note `MGLMultiPolygon` objects cannot be added to a map view using
-    `-[MGLMapView addAnnotations:]` and related methods.
+ You cannot add an `MGLMultiPolygon` object directly to a map view using
+ `-[MGLMapView addAnnotation:]` or `-[MGLMapView addOverlay:]`. However, you can
+ add the `polygons` array’s items as overlays individually.
  */
 MGL_EXPORT
 @interface MGLMultiPolygon : MGLShape <MGLOverlay>