annotation header docs & script updates

include/mbgl/ios/MGLAnnotation.h

@@ -1,24 +1,27 @@
-//
-//  MGLAnnotation.h
-//  mbgl
-//
-//  Created by Minh Nguyen on 2015-03-04.
-//
-//
-
 #import <Foundation/Foundation.h>
 
+/** The MGLAnnotation protocol is used to provide annotation-related information to a map view. To use this protocol, you adopt it in any custom objects that store or represent annotation data. Each object then serves as the source of information about a single map annotation and provides critical information, such as the annotation’s location on the map. Annotation objects do not provide the visual representation of the annotation but typically coordinate (in conjunction with the map view’s delegate) the creation of an appropriate objects to handle the display.
+*
+*   An object that adopts this protocol must implement the `coordinate` property. The other methods of this protocol are optional. */
 @protocol MGLAnnotation <NSObject>
 
-//! The receiver’s center, expressed as a coordinate on the containing map.
+/** @name Position Attributes */
+
+/** The center point (specified as a map coordinate) of the annotation. (required) (read-only) */
 @property (nonatomic, readonly) CLLocationCoordinate2D coordinate;
 
 @optional
 
-//! The receiver’s title string.
+/** @name Title Attributes */
+
+/** The string containing the annotation’s title.
+*
+* Although this property is optional, if you support the selection of annotations in your map view, you are expected to provide this property. This string is displayed in the callout for the associated annotation. */
 @property (nonatomic, readonly, copy) NSString *title;
 
-//! The receiver’s subtitle string.
+/** The string containing the annotation’s subtitle.
+*
+*   This string is displayed in the callout for the associated annotation. */
 @property (nonatomic, readonly, copy) NSString *subtitle;
 
 @end

include/mbgl/ios/MGLMapView.h

@@ -187,27 +187,55 @@
 
 #pragma mark - Annotating the Map
 
+/** @name Annotating the Map */
+
+/** The complete list of annotations associated with the receiver. (read-only)
+*
+*   The objects in this array must adopt the MGLAnnotation protocol. If no annotations are associated with the map view, the value of this property is `nil`. */
 @property (nonatomic, readonly) NSArray *annotations;
 
-// TODO
+/** Adds the specified annotation to the map view.
+*   @param annotation The annotation object to add to the receiver. This object must conform to the MGLAnnotation protocol. The map view retains the specified object. */
 - (void)addAnnotation:(id <MGLAnnotation>)annotation;
 
-// TODO
+/** Adds an array of annotation objects to the map view.
+*   @param annotations An array of annotation objects. Each object in the array must conform to the MGLAnnotation protocol. The map view retains the individual annotation objects. */
 - (void)addAnnotations:(NSArray *)annotations;
 
-// TODO
+/** Removes the specified annotation object from the map view.
+*
+*   Removing an annotation object disassociates it from the map view entirely, preventing it from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete a given annotation.
+*
+*   @param annotation The annotation object to remove. This object must conform to the MGLAnnotation protocol. */
 - (void)removeAnnotation:(id <MGLAnnotation>)annotation;
 
-// TODO
+/** Removes an array of annotation objects from the map view.
+*
+*   Removing annotation objects disassociates them from the map view entirely, preventing them from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete the specified annotations.
+*
+*   @param annotations The array of annotations to remove. Objects in the array must conform to the MGLAnnotation protocol. */
 - (void)removeAnnotations:(NSArray *)annotations;
 
-// TODO
+//- (void)showAnnotations:(NSArray *)annotations animated:(BOOL)animated;
+
+//- (NSSet *)annotationsInMapRect:(MKMapRect)mapRect
+
+/** The annotations that are currently selected.
+*
+*   Assigning a new array to this property selects only the first annotation in the array. */
 @property (nonatomic, copy) NSArray *selectedAnnotations;
 
-// TODO
+/** Selects the specified annotation and displays a callout view for it.
+*
+*   If the specified annotation is not onscreen, this method has no effect.
+*
+*   @param annotation The annotation object to select.
+*   @param animated If `YES`, the callout view is animated into position. */
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
-// TODO
+/** Deselects the specified annotation and hides its callout view.
+*   @param annotation The annotation object to deselect.
+*   @param animated If `YES`, the callout view is animated offscreen. */
 - (void)deselectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
 #pragma mark - Debugging
@@ -227,12 +255,17 @@
 
 @end
 
-// TODO
+/** The MGLMapViewDelegate protocol defines a set of optional methods that you can use to receive map-related update messages. Because many map operations require the MGLMapView class to load data asynchronously, the map view calls these methods to notify your application when specific operations complete. The map view also uses these methods to request annotation marker symbology and to manage interactions with those markers. */
 @protocol MGLMapViewDelegate <NSObject>
 
 @optional
 
-//! Delegates implement this method to return a string containing the name of a symbol to use for the given annotation.
+/** @name Managing the Display of Annotations */
+
+/** Returns the style's symbol name to use for the marker for the specified point annotation object.
+*   @param mapView The map view that requested the annotation symbol name.
+*   @param annotation The object representing the annotation that is about to be displayed. 
+*   @return The marker symbol to display for the specified annotation or `nil` if you want to display the default symbol. */
 - (NSString *)mapView:(MGLMapView *)mapView symbolNameForAnnotation:(id <MGLAnnotation>)annotation;
 
 // Responding to Map Position Changes

ios/docs/install_docs.sh

@@ -5,7 +5,7 @@ if [ -z `which appledoc` ]; then
     exit 1
 fi
 
-VERSION=$( git tag | sort -r | sed -n '1p' )
+VERSION=$( git tag | grep ^[0-9] | sort -r | sed -n '1p' )
 echo "Creating new docs for $VERSION..."
 echo
 
@@ -15,10 +15,4 @@ appledoc \
     --project-company Mapbox \
     --create-docset \
     --company-id com.mapbox \
-    --ignore app \
-    --ignore dist \
-    --ignore pkg \
-    --ignore test \
-    --ignore .m \
-    --ignore .mm \
-    .
+    ../../include/mbgl/ios

ios/docs/remove_docs.sh

@@ -4,4 +4,4 @@ echo
 echo "Removing docs from ~/Library/Developer/Shared/Documentation/DocSets..."
 echo
 
-rm -rfv ~/Library/Developer/Shared/Documentation/DocSets/com.mapbox.Mapbox-GL-*
+rm -rfv ~/Library/Developer/Shared/Documentation/DocSets/com.mapbox.Mapbox-GL-*