[ios] Add method documentation for view based annotations.

2 files changed, 41 insertions, 0 deletions

diff --git a/platform/ios/src/MGLAnnotationView.h b/platform/ios/src/MGLAnnotationView.h
index 475d9aa758..bc2494e9fc 100644
--- a/platform/ios/src/MGLAnnotationView.h
+++ b/platform/ios/src/MGLAnnotationView.h
@@ -4,15 +4,35 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/** The MGLAnnotationView class is responsible for representing point-based annotation markers as a view. Annotation views represent an annotation object, which is an object that corresponds to the MGLAnnotation protocol. When an annotation’s coordinate point is visible on the map view, the map view delegate is asked to provide a corresponding annotation view. If an annotation view is created with a reuse identifier, the map view may recycle the view when it goes offscreen. */
 @interface MGLAnnotationView : UIView
 
+/**
+ Initializes and returns a new annotation view object.
+ 
+ @param reuseIdentifier The string that identifies that this annotation view is reusable.
+ @return The initialized annotation view object or `nil` if there was a problem initializing the object.
+ */
 - (instancetype)initWithReuseIdentifier:(NSString *)reuseIdentifier;
 
 /**
  The string that identifies that this annotation view is reusable. (read-only)
+ 
+ You specify the reuse identifier when you create the view. You use the identifier later to retrieve an annotation view that was
+ created previously but which is currently unused because its annotation is not on screen.
+ 
+ If you define distinctly different types of annotations (with distinctly different annotation views to go with them), you can
+ differentiate between the annotation types by specifying different reuse identifiers for each one.
  */
 @property (nonatomic, readonly, nullable) NSString *reuseIdentifier;
 
+
+/**
+ Called when the view is removed from the reuse queue.
+
+ The default implementation of this method does nothing. You can override it in your custom annotation views and use it to put the view 
+ in a known state before it is returned to your map view delegate.
+ */
 - (void)prepareForReuse;
 
 @end
diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 9435564942..b6fd1c4ffd 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -932,6 +932,20 @@ IB_DESIGNABLE
  */
 - (nullable MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier;
 
+/**
+ Returns a reusable annotation view object associated with its identifier.
+ 
+ For performance reasons, you should generally reuse `MGLAnnotationView`
+ objects for identical-looking annotations in your map views. Dequeueing
+ saves time and memory during performance-critical operations such as
+ scrolling.
+ 
+ @param identifier A string identifying the annotation view to be reused.
+    This string is the same one you specify when initially returning the
+    annotation view object using the `-mapView:viewForAnnotation:` method.
+ @return An annotation view object with the given identifier, or `nil` if no
+    such object exists in the reuse queue.
+ */
 - (nullable MGLAnnotationView *)dequeueReusableAnnotationViewWithIdentifier:(NSString *)identifier;
 
 #pragma mark Managing Annotation Selections
@@ -1154,6 +1168,13 @@ IB_DESIGNABLE
 
 #pragma mark Managing the Display of Annotations
 
+/**
+ Returns a view object to use for the marker for the specified point annotation object.
+ 
+ @param mapView The map view that requested the annotation view.
+ @param annotation The object representing the annotation that is about to be displayed.
+ @return The view object to display for the specified annotation or `nil` if you want to display the default marker image.
+ */
 - (nullable MGLAnnotationView *)mapView:(MGLMapView *)mapView viewForAnnotation:(id <MGLAnnotation>)annotation;
 
 /**