From 1420a49689c3b48dd429fb5a3640596a9e7c9623 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguy=E1=BB=85n?= Date: Sun, 6 Dec 2015 15:24:58 -0800 Subject: [PATCH] [ios] Generate API documentation using jazzy Replaced appledoc usage with jazzy, which understands modern Objective-C syntax by virtue of using Clang ASTs. Nevertheless, we have to make lots of changes to our documentation syntax, which was tailored to appledocs quirks. The new syntax jives much better with what Xcode expects in terms of auto-indentation and Quick Help. Fixes #1420. --- .jazzy.yaml | 51 ++ CHANGELOG.md | 1 + include/mbgl/darwin/MGLAnnotation.h | 28 +- include/mbgl/darwin/MGLGeometry.h | 18 +- include/mbgl/darwin/MGLMapCamera.h | 15 + include/mbgl/darwin/MGLMultiPoint.h | 9 +- include/mbgl/darwin/MGLOverlay.h | 41 +- include/mbgl/darwin/MGLPolygon.h | 11 +- include/mbgl/darwin/MGLPolyline.h | 11 +- include/mbgl/darwin/MGLStyle.h | 42 +- include/mbgl/darwin/MGLTypes.h | 1 + include/mbgl/ios/MGLAccountManager.h | 29 +- include/mbgl/ios/MGLAnnotationImage.h | 35 +- include/mbgl/ios/MGLMapView.h | 954 +++++++++++++++----------- include/mbgl/ios/MGLUserLocation.h | 20 +- platform/ios/INSTALL.md | 7 +- platform/ios/bitrise.yml | 3 +- platform/ios/scripts/install.sh | 7 +- platform/ios/scripts/package.sh | 49 +- 19 files changed, 803 insertions(+), 529 deletions(-) create mode 100644 .jazzy.yaml diff --git a/.jazzy.yaml b/.jazzy.yaml new file mode 100644 index 000000000..35c4e9a8e --- /dev/null +++ b/.jazzy.yaml @@ -0,0 +1,51 @@ +module_name: Mapbox +author_name: Mapbox +author_url: https://www.mapbox.com/ +github_url: https://github.com/mapbox/mapbox-gl-native +dash_url: https://www.mapbox.com/ios-sdk/docsets/Mapbox.xml +copyright: '© 2014–2015 [Mapbox](https://www.mapbox.com/). See [license](https://github.com/mapbox/mapbox-gl-native/blob/master/LICENSE.md) for more details.' + +custom_head: | + + +objc_mode: Yes +skip_undocumented: Yes +hide_documentation_coverage: Yes +umbrella_header: include/mbgl/ios/Mapbox.h +framework_root: include/mbgl/darwin + +custom_categories: + - name: Map + children: + - MGLAccountManager + - MGLMapCamera + - MGLMapView + - MGLMapViewDelegate + - MGLStyle + - MGLUserTrackingMode + - name: Annotations + children: + - MGLAnnotation + - MGLAnnotationImage + - MGLMultiPoint + - MGLPointAnnotation + - MGLPolygon + - MGLPolyline + - MGLOverlay + - MGLShape + - MGLUserLocation + - name: Geometry + children: + - MGLCoordinateBounds + - MGLCoordinateBoundsEqualToCoordinateBounds + - MGLCoordinateBoundsGetCoordinateSpan + - MGLCoordinateBoundsIsEmpty + - MGLCoordinateBoundsMake + - MGLCoordinateBoundsOffset + - MGLCoordinateSpan + - MGLCoordinateSpanEqualToCoordinateSpan + - MGLCoordinateSpanMake + - MGLCoordinateSpanZero + - MGLDegreesFromRadians + - MGLRadiansFromDegrees + - MGLStringFromCoordinateBounds diff --git a/CHANGELOG.md b/CHANGELOG.md index ed2070a9d..91f094bc2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,7 @@ Known issues: - Fixed an issue with small map views not properly fitting annotations within bounds. (#[3407](https://github.com/mapbox/mapbox-gl-native/pull/3407)) - The map will now snap to north. ([#3403](https://github.com/mapbox/mapbox-gl-native/pull/3403)) - The map view’s background can now be transparent or translucent, as long as the style’s background layer is transparent or translucent and `MGLMapView.opaque` is set to `NO`. ([#3096](https://github.com/mapbox/mapbox-gl-native/pull/3096)) +- Documentation is now generated by [jazzy](https://github.com/realm/jazzy) instead of appledoc. ♪♫ ([#3203](https://github.com/mapbox/mapbox-gl-native/pull/3203)) ## iOS 3.0.1 diff --git a/include/mbgl/darwin/MGLAnnotation.h b/include/mbgl/darwin/MGLAnnotation.h index 34b086f22..e4726f950 100644 --- a/include/mbgl/darwin/MGLAnnotation.h +++ b/include/mbgl/darwin/MGLAnnotation.h @@ -6,28 +6,34 @@ NS_ASSUME_NONNULL_BEGIN -/** 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. */ +/** + 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 -/** @name Position Attributes */ +#pragma mark Position Attributes /** The center point (specified as a map coordinate) of the annotation. (required) (read-only) */ @property (nonatomic, readonly) CLLocationCoordinate2D coordinate; @optional -/** @name Title Attributes */ +#pragma mark 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. */ +/** + 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, nullable) NSString *title; -/** The string containing the annotation’s subtitle. -* -* This string is displayed in the callout for the associated annotation. */ +/** + The string containing the annotation’s subtitle. + + This string is displayed in the callout for the associated annotation. + */ @property (nonatomic, readonly, copy, nullable) NSString *subtitle; #if !TARGET_OS_IPHONE diff --git a/include/mbgl/darwin/MGLGeometry.h b/include/mbgl/darwin/MGLGeometry.h index 5337dca6b..8d185805d 100644 --- a/include/mbgl/darwin/MGLGeometry.h +++ b/include/mbgl/darwin/MGLGeometry.h @@ -6,13 +6,15 @@ NS_ASSUME_NONNULL_BEGIN -/** Defines the area spanned by an MGLCoordinateBounds. */ -typedef struct { +/** Defines the area spanned by an `MGLCoordinateBounds`. */ +typedef struct MGLCoordinateSpan { + /** Latitudes spanned by an `MGLCoordinateBounds`. */ CLLocationDegrees latitudeDelta; + /** Longitudes spanned by an `MGLCoordinateBounds`. */ CLLocationDegrees longitudeDelta; } MGLCoordinateSpan; -/** Creates a new MGLCoordinateSpan from the given latitudinal and longitudinal deltas. */ +/** Creates a new `MGLCoordinateSpan` from the given latitudinal and longitudinal deltas. */ NS_INLINE MGLCoordinateSpan MGLCoordinateSpanMake(CLLocationDegrees latitudeDelta, CLLocationDegrees longitudeDelta) { MGLCoordinateSpan span; span.latitudeDelta = latitudeDelta; @@ -30,12 +32,14 @@ NS_INLINE BOOL MGLCoordinateSpanEqualToCoordinateSpan(MGLCoordinateSpan span1, M extern const MGLCoordinateSpan MGLCoordinateSpanZero; /** A rectangular area as measured on a two-dimensional map projection. */ -typedef struct { +typedef struct MGLCoordinateBounds { + /** Coordinate at the southwest corner. */ CLLocationCoordinate2D sw; + /** Coordinate at the northeast corner. */ CLLocationCoordinate2D ne; } MGLCoordinateBounds; -/** Creates a new MGLCoordinateBounds structure from the given southwest and northeast coordinates. */ +/** Creates a new `MGLCoordinateBounds` structure from the given southwest and northeast coordinates. */ NS_INLINE MGLCoordinateBounds MGLCoordinateBoundsMake(CLLocationCoordinate2D sw, CLLocationCoordinate2D ne) { MGLCoordinateBounds bounds; bounds.sw = sw; @@ -68,8 +72,8 @@ NS_INLINE MGLCoordinateBounds MGLCoordinateBoundsOffset(MGLCoordinateBounds boun } /** Returns `YES` if the coordinate bounds covers no area. -* -* Note that a bounds may be empty but have a non-zero coordinate span (e.g., when its northeast point lies due north of its southwest point). */ + + Note that a bounds may be empty but have a non-zero coordinate span (e.g., when its northeast point lies due north of its southwest point). */ NS_INLINE BOOL MGLCoordinateBoundsIsEmpty(MGLCoordinateBounds bounds) { MGLCoordinateSpan span = MGLCoordinateBoundsGetCoordinateSpan(bounds); return span.latitudeDelta == 0 || span.longitudeDelta == 0; diff --git a/include/mbgl/darwin/MGLMapCamera.h b/include/mbgl/darwin/MGLMapCamera.h index 7c00ad866..3cb902ba5 100644 --- a/include/mbgl/darwin/MGLMapCamera.h +++ b/include/mbgl/darwin/MGLMapCamera.h @@ -24,10 +24,25 @@ NS_ASSUME_NONNULL_BEGIN /** Returns a new camera with all properties set to 0. */ + (instancetype)camera; +/** + Returns a new camera using based on information about the camera’s viewpoint and focus point. + + @param centerCoordinate The geographic coordinate on which the map should be centered. + @param eyeCoordinate The geometric coordinate at which the camera should be situated. + @param eyeAltitude The altitude (measured in meters) above the map at which the camera should be situated. The altitude may be less than the distance from the camera’s viewpoint to the camera’s focus point. + */ + (instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate fromEyeCoordinate:(CLLocationCoordinate2D)eyeCoordinate eyeAltitude:(CLLocationDistance)eyeAltitude; +/** + Returns a new camera with the given distance, pitch, and heading. + + @param centerCoordinate The geographic coordinate on which the map should be centered. + @param distance The straight-line distance from the viewpoint to the `centerCoordinate`. + @param pitch The viewing angle of the camera, measured in degrees. A value of `0` results in a camera pointed straight down at the map. Angles greater than `0` result in a camera angled toward the horizon. + @param heading The camera’s heading, measured in degrees clockwise from true north. A value of `0` means that the top edge of the map view corresponds to true north. The value `90` means the top of the map is pointing due east. The value `180` means the top of the map points due south, and so on. + */ + (instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate fromDistance:(CLLocationDistance)distance pitch:(CGFloat)pitch diff --git a/include/mbgl/darwin/MGLMultiPoint.h b/include/mbgl/darwin/MGLMultiPoint.h index 5c58016df..ad9db1e68 100644 --- a/include/mbgl/darwin/MGLMultiPoint.h +++ b/include/mbgl/darwin/MGLMultiPoint.h @@ -13,9 +13,12 @@ NS_ASSUME_NONNULL_BEGIN /** The number of points associated with the shape. (read-only) */ @property (nonatomic, readonly) NSUInteger pointCount; -/** Retrieves one or more coordinates associated with the shape. -* @param coords On input, you must provide a C array of structures large enough to hold the desired number of coordinates. On output, this structure contains the requested coordinate data. -* @param range The range of points you want. The `location` field indicates the first point you are requesting, with `0` being the first point, `1` being the second point, and so on. The `length` field indicates the number of points you want. The array in _`coords`_ must be large enough to accommodate the number of requested coordinates. */ +/** + Retrieves one or more coordinates associated with the shape. + + @param coords On input, you must provide a C array of structures large enough to hold the desired number of coordinates. On output, this structure contains the requested coordinate data. + @param range The range of points you want. The `location` field indicates the first point you are requesting, with `0` being the first point, `1` being the second point, and so on. The `length` field indicates the number of points you want. The array in _`coords`_ must be large enough to accommodate the number of requested coordinates. + */ - (void)getCoordinates:(CLLocationCoordinate2D *)coords range:(NSRange)range; @end diff --git a/include/mbgl/darwin/MGLOverlay.h b/include/mbgl/darwin/MGLOverlay.h index ab827c0d2..aa80fe390 100644 --- a/include/mbgl/darwin/MGLOverlay.h +++ b/include/mbgl/darwin/MGLOverlay.h @@ -8,28 +8,37 @@ NS_ASSUME_NONNULL_BEGIN -/** The `MGLOverlay` protocol defines a specific type of annotation that represents both a point and an area on a map. Overlay objects are essentially data objects that contain the geographic data needed to represent the map area. For example, overlays can take the form of common shapes such as rectangles and circles. They can also describe polygons and other complex shapes. -* -* You use overlays to layer more sophisticated content on top of a map view. For example, you could use an overlay to show the boundaries of a national park or trace a bus route along city streets. The Mapbox iOS SDK defines several concrete classes that conform to this protocol and define standard shapes. -* -* Because overlays are also annotations, they have similar usage pattern to annotations. When added to a map view using the `addOverlay:` method, that view detects whenever the overlay’s defined region intersects the visible portion of the map. At that point, the map view asks its delegate to provide a special overlay view to draw the visual representation of the overlay. If you add an overlay to a map view as an annotation instead, it is treated as an annotation with a single point. */ +/** + The `MGLOverlay` protocol defines a specific type of annotation that represents both a point and an area on a map. Overlay objects are essentially data objects that contain the geographic data needed to represent the map area. For example, overlays can take the form of common shapes such as rectangles and circles. They can also describe polygons and other complex shapes. + + You use overlays to layer more sophisticated content on top of a map view. For example, you could use an overlay to show the boundaries of a national park or trace a bus route along city streets. The Mapbox iOS SDK defines several concrete classes that conform to this protocol and define standard shapes. + + Because overlays are also annotations, they have similar usage pattern to annotations. When added to a map view using the `-addOverlay:` method, that view detects whenever the overlay’s defined region intersects the visible portion of the map. At that point, the map view asks its delegate to provide a special overlay view to draw the visual representation of the overlay. If you add an overlay to a map view as an annotation instead, it is treated as an annotation with a single point. + */ @protocol MGLOverlay -/* The approximate center point of the overlay area. (required) (read-only) -* -* This point is typically set to the center point of the map’s bounding rectangle. It is used as the anchor point for any callouts displayed for the annotation. */ +/** + The approximate center point of the overlay area. (required) (read-only) + + This point is typically set to the center point of the map’s bounding rectangle. It is used as the anchor point for any callouts displayed for the annotation. + */ @property (nonatomic, readonly) CLLocationCoordinate2D coordinate; -/** The cooordinate rectangle that encompasses the overlay. (required) (read-only) -* -* This property contains the smallest rectangle that completely encompasses the overlay. Implementers of this protocol must set this area when implementing their overlay class, and after setting it, you must not change it. */ +/** + The cooordinate rectangle that encompasses the overlay. (required) (read-only) + + This property contains the smallest rectangle that completely encompasses the overlay. Implementers of this protocol must set this area when implementing their overlay class, and after setting it, you must not change it. + */ @property (nonatomic, readonly) MGLCoordinateBounds overlayBounds; -/** Returns a Boolean indicating whether the specified rectangle intersects the receiver’s shape. -* -* You can implement this method to provide more specific bounds checking for an overlay. If you do not implement it, the bounding rectangle is used to detect intersections. -* @param overlayBounds The rectangle to intersect with the receiver’s area. -* @return `YES` if any part of the map rectangle intersects the receiver’s shape or `NO` if it does not. */ +/** + Returns a Boolean indicating whether the specified rectangle intersects the receiver’s shape. + + You can implement this method to provide more specific bounds checking for an overlay. If you do not implement it, the bounding rectangle is used to detect intersections. + + @param overlayBounds The rectangle to intersect with the receiver’s area. + @return `YES` if any part of the map rectangle intersects the receiver’s shape or `NO` if it does not. + */ - (BOOL)intersectsOverlayBounds:(MGLCoordinateBounds)overlayBounds; @end diff --git a/include/mbgl/darwin/MGLPolygon.h b/include/mbgl/darwin/MGLPolygon.h index a19b984f1..c5480264f 100644 --- a/include/mbgl/darwin/MGLPolygon.h +++ b/include/mbgl/darwin/MGLPolygon.h @@ -11,10 +11,13 @@ 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. */ @interface MGLPolygon : MGLMultiPoint -/** Creates and returns an `MGLPolygon` object from the specified set of coordinates. -* @param coords The array of coordinates defining the shape. The data in this array is copied to the new object. -* @param count The number of items in the _`coords`_ array. -* @return A new polygon object. */ +/** + Creates and returns an `MGLPolygon` object from the specified set of coordinates. + + @param coords The array of coordinates defining the shape. The data in this array is copied to the new object. + @param count The number of items in the `coords` array. + @return A new polygon object. + */ + (instancetype)polygonWithCoordinates:(CLLocationCoordinate2D *)coords count:(NSUInteger)count; diff --git a/include/mbgl/darwin/MGLPolyline.h b/include/mbgl/darwin/MGLPolyline.h index c849bc987..c28299c7e 100644 --- a/include/mbgl/darwin/MGLPolyline.h +++ b/include/mbgl/darwin/MGLPolyline.h @@ -11,10 +11,13 @@ NS_ASSUME_NONNULL_BEGIN /** The `MGLPolyline` class represents a shape consisting of one or more points that define connecting line segments. The points are connected end-to-end in the order they are provided. The first and last points are not connected to each other. */ @interface MGLPolyline : MGLMultiPoint -/** Creates and returns an `MGLPolyline` object from the specified set of coordinates. -* @param coords The array of coordinates defining the shape. The data in this array is copied to the new object. -* @param count The number of items in the _`coords`_ array. -* @return A new polyline object. */ +/** + Creates and returns an `MGLPolyline` object from the specified set of coordinates. + + @param coords The array of coordinates defining the shape. The data in this array is copied to the new object. + @param count The number of items in the `coords` array. + @return A new polyline object. + */ + (instancetype)polylineWithCoordinates:(CLLocationCoordinate2D *)coords count:(NSUInteger)count; diff --git a/include/mbgl/darwin/MGLStyle.h b/include/mbgl/darwin/MGLStyle.h index 88cb8aaa8..e5b2de877 100644 --- a/include/mbgl/darwin/MGLStyle.h +++ b/include/mbgl/darwin/MGLStyle.h @@ -7,28 +7,46 @@ NS_ASSUME_NONNULL_BEGIN /** A collection of convenience methods for creating style URLs of default styles provided by Mapbox. These instances of NSURL are cached. */ @interface MGLStyle : NSObject -/** Returns the Streets style URL. -* Mapbox Streets is a complete base map, perfect for incorporating your own data. */ +/** + Returns the Streets style URL. + + Mapbox Streets is a complete base map, perfect for incorporating your own data. + */ + (NSURL *)streetsStyleURL; -/** Returns the Emerald style URL. -* Emerald is a versatile style with emphasis on road networks and public transportation. */ +/** + Returns the Emerald style URL. + + Emerald is a versatile style with emphasis on road networks and public transportation. + */ + (NSURL *)emeraldStyleURL; -/** Returns the Light style URL. -* Light is a subtle, light-colored backdrop for data visualizations. */ +/** + Returns the Light style URL. + + Light is a subtle, light-colored backdrop for data visualizations. + */ + (NSURL *)lightStyleURL; -/** Returns the Dark style URL. -* Dark is a subtle, dark-colored backdrop for data visualizations. */ +/** + Returns the Dark style URL. + + Dark is a subtle, dark-colored backdrop for data visualizations. + */ + (NSURL *)darkStyleURL; -/** Returns the Satellite style URL. -* Mapbox Satellite is a beautiful global satellite and aerial imagery layer. */ +/** + Returns the Satellite style URL. + + Mapbox Satellite is a beautiful global satellite and aerial imagery layer. + */ + (NSURL *)satelliteStyleURL; -/** Returns the Hybrid style URL. -* Hybrid combines the global satellite and aerial imagery of Mapbox Satellite with unobtrusive labels. */ +/** + Returns the Hybrid style URL. + + Hybrid combines the global satellite and aerial imagery of Mapbox Satellite with unobtrusive labels. + */ + (NSURL *)hybridStyleURL; - (instancetype)init NS_UNAVAILABLE; diff --git a/include/mbgl/darwin/MGLTypes.h b/include/mbgl/darwin/MGLTypes.h index b86ecc35e..c107055db 100644 --- a/include/mbgl/darwin/MGLTypes.h +++ b/include/mbgl/darwin/MGLTypes.h @@ -12,6 +12,7 @@ NS_ASSUME_NONNULL_BEGIN +/** Indicates an error occurred in the Mapbox SDK. */ extern NSString * const MGLErrorDomain; /** The mode used to track the user location on the map. */ diff --git a/include/mbgl/ios/MGLAccountManager.h b/include/mbgl/ios/MGLAccountManager.h index 4c239d6a1..2b3b1784f 100644 --- a/include/mbgl/ios/MGLAccountManager.h +++ b/include/mbgl/ios/MGLAccountManager.h @@ -7,23 +7,30 @@ NS_ASSUME_NONNULL_BEGIN /** The MGLAccountManager object provides a global way to set a Mapbox API access token, as well as other settings used framework-wide. */ @interface MGLAccountManager : NSObject -/** @name Authorizing Access */ +#pragma mark Authorizing Access -/** Set the Mapbox API access token for the framework. -* -* You can set an access token on MGLAccountManager or on an individual map view. The same token is used throughout the framework. -* @param accessToken The Mapbox API access token. */ +/** + Set the Mapbox API access token for the framework. + + You can set an access token on MGLAccountManager or on an individual map view. The same token is used throughout the framework. + @param accessToken The Mapbox API access token. + */ + (void)setAccessToken:(nullable NSString *)accessToken; -/** Retreive the Mapbox API access token for the framework. -* -* You can set an access token on MGLAccountManager or on an individual map view. The same token is used throughout the framework. -* @return accessToken The Mapbox API access token. */ +/** + Retreive the Mapbox API access token for the framework. + + You can set an access token on MGLAccountManager or on an individual map view. The same token is used throughout the framework. + + @return accessToken The Mapbox API access token. + */ + (nullable NSString *)accessToken; -/** @name Providing User Metrics Opt-Out */ +#pragma mark Providing User Metrics Opt-Out -/** Whether in-app user metrics opt-out is configured. If set to the default value of `NO`, a user opt-out preference is expected in a `Settings.bundle` that shows in the application's section within the system Settings app. */ +/** + Whether in-app user metrics opt-out is configured. If set to the default value of `NO`, a user opt-out preference is expected in a `Settings.bundle` that shows in the application's section within the system Settings app. + */ + (BOOL)mapboxMetricsEnabledSettingShownInApp; @end diff --git a/include/mbgl/ios/MGLAnnotationImage.h b/include/mbgl/ios/MGLAnnotationImage.h index f48a3cfb4..f9d9e7056 100644 --- a/include/mbgl/ios/MGLAnnotationImage.h +++ b/include/mbgl/ios/MGLAnnotationImage.h @@ -7,29 +7,36 @@ NS_ASSUME_NONNULL_BEGIN /** The MGLAnnotationImage class is responsible for presenting point-based annotations visually on a map view. Annotation image objects wrap `UIImage` objects and may be recycled later and put into a reuse queue that is maintained by the map view. */ @interface MGLAnnotationImage : NSObject -/** @name Initializing and Preparing the Image Object */ +#pragma mark Initializing and Preparing the Image Object -/** Initializes and returns a new annotation image object. -* @param image The image to be displayed for the annotation. -* @param reuseIdentifier The string that identifies that this annotation image is reusable. -* @return The initialized annotation image object or `nil` if there was a problem initializing the object. */ +/** + Initializes and returns a new annotation image object. + + @param image The image to be displayed for the annotation. + @param reuseIdentifier The string that identifies that this annotation image is reusable. + @return The initialized annotation image object or `nil` if there was a problem initializing the object. + */ + (instancetype)annotationImageWithImage:(UIImage *)image reuseIdentifier:(NSString *)reuseIdentifier; -/** @name Getting and Setting Attributes */ +#pragma mark Getting and Setting Attributes /** The image to be displayed for the annotation. */ @property (nonatomic, strong) UIImage *image; -/** The string that identifies that this annotation image is reusable. (read-only) -* -* You specify the reuse identifier when you create the image object. You use this type later to retrieve an annotation image object 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 images to go with them), you can differentiate between the annotation types by specifying different reuse identifiers for each one. */ +/** + The string that identifies that this annotation image is reusable. (read-only) + + You specify the reuse identifier when you create the image object. You use this type later to retrieve an annotation image object 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 images to go with them), you can differentiate between the annotation types by specifying different reuse identifiers for each one. + */ @property (nonatomic, readonly) NSString *reuseIdentifier; -/** A Boolean value indicating whether the annotation is enabled. -* -* The default value of this property is `YES`. If the value of this property is `NO`, the annotation image ignores touch events and cannot be selected. */ +/** + A Boolean value indicating whether the annotation is enabled. + + The default value of this property is `YES`. If the value of this property is `NO`, the annotation image ignores touch events and cannot be selected. + */ @property (nonatomic, getter=isEnabled) BOOL enabled; @end diff --git a/include/mbgl/ios/MGLMapView.h b/include/mbgl/ios/MGLMapView.h index ebf7509a3..88c27d160 100644 --- a/include/mbgl/ios/MGLMapView.h +++ b/include/mbgl/ios/MGLMapView.h @@ -18,59 +18,71 @@ NS_ASSUME_NONNULL_BEGIN @protocol MGLAnnotation; @protocol MGLOverlay; -/** An MGLMapView object provides an embeddable map interface, similar to the one provided by Apple's MapKit. You use this class to display map information and to manipulate the map contents from your application. You can center the map on a given coordinate, specify the size of the area you want to display, and style the features of the map to fit your application's use case. -* -* Use of MGLMapView requires a Mapbox API access token. Obtain an access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). If you instantiate an MGLMapView from Interface Builder, rendering of the map won't begin until the accessToken property has been set. -* -* @warning Please note that you are responsible for getting permission to use the map data, and for ensuring your use adheres to the relevant terms of use. */ +/** + An MGLMapView object provides an embeddable map interface, similar to the one provided by Apple's MapKit. You use this class to display map information and to manipulate the map contents from your application. You can center the map on a given coordinate, specify the size of the area you want to display, and style the features of the map to fit your application's use case. + + Use of MGLMapView requires a Mapbox API access token. Obtain an access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). If you instantiate an MGLMapView from Interface Builder, rendering of the map won't begin until the accessToken property has been set. + + @warning Please note that you are responsible for getting permission to use the map data, and for ensuring your use adheres to the relevant terms of use. + */ IB_DESIGNABLE @interface MGLMapView : UIView -#pragma mark - Initializing a Map View +#pragma mark Initializing a Map View -/** @name Initializing a Map View */ - -/** Initializes and returns a newly allocated map view with the specified frame and the default style. -* @param frame The frame for the view, measured in points. -* @return An initialized map view. */ +/** + Initializes and returns a newly allocated map view with the specified frame and the default style. + + @param frame The frame for the view, measured in points. + @return An initialized map view. + */ - (instancetype)initWithFrame:(CGRect)frame; -/** Initializes and returns a newly allocated map view with the specified frame and style URL. -* @param frame The frame for the view, measured in points. -* @param styleURL The map style URL to use. Can be either an HTTP/HTTPS URL or a Mapbox map ID style URL (`mapbox://styles//