[osx] Commented private headers and implementation files

include/mbgl/osx/MGLMapView+IBAdditions.h

@@ -6,19 +6,27 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface MGLMapView (IBAdditions)
 
+#if TARGET_INTERFACE_BUILDER
+
 // Core properties that can be manipulated in the Attributes inspector in
 // Interface Builder. These redeclarations merely add the IBInspectable keyword.
 // They appear here to ensure that they appear above the convenience properties;
 // inspectables declared in MGLMapView.h are always sorted before those in
 // MGLMapView+IBAdditions.h, due to ASCII sort order.
 
-#if TARGET_INTERFACE_BUILDER
 // We want this property to look like a URL bar in the Attributes inspector, but
 // just calling it styleURL would violate Cocoa naming conventions and conflict
 // with the existing NSURL property. Fortunately, IB strips out the two
 // underscores for display.
+
+/**
+    URL of the style currently displayed in the receiver.
+ 
+    The URL may be a full HTTP or HTTPS URL, a Mapbox URL indicating the style’s
+    map ID (`mapbox://styles/<user>/<style>`), or a path to a local file
+    relative to the application’s resource path.
+ */
 @property (nonatomic, nullable) IBInspectable NSString *styleURL__;
-#endif
 
 // Convenience properties related to the initial viewport. These properties
 // are not meant to be used outside of Interface Builder. latitude and longitude
@@ -26,19 +34,44 @@ NS_ASSUME_NONNULL_BEGIN
 // must use the type double because Interface Builder is unaware that
 // CLLocationDegrees is a typedef for double.
 
+/** The initial center latitude. */
 @property (nonatomic) IBInspectable double latitude;
+
+/** The initial center longitude. */
 @property (nonatomic) IBInspectable double longitude;
+
 @property (nonatomic) IBInspectable double zoomLevel;
 
 // Renamed properties. Interface Builder derives the display name of each
 // inspectable from the runtime name, but runtime names don’t always make sense
 // in UI.
 
+/**
+    A Boolean value that determines whether the user may zoom the map, changing
+    its zoom level.
+ */
 @property (nonatomic) IBInspectable BOOL allowsZooming;
+
+/**
+    A Boolean value that determines whether the user may scroll around the map,
+    changing its center coordinate.
+ */
 @property (nonatomic) IBInspectable BOOL allowsScrolling;
+
+/**
+    A Boolean value that determines whether the user may rotate the map,
+    changing its direction.
+ */
 @property (nonatomic) IBInspectable BOOL allowsRotating;
+
+/**
+    A Boolean value that determines whether the user may tilt the map, changing
+    its pitch.
+ */
 @property (nonatomic) IBInspectable BOOL allowsTilting;
 
+#endif
+
 @end
 
 NS_ASSUME_NONNULL_END

include/mbgl/osx/MGLMapView.h

@@ -38,6 +38,15 @@ IB_DESIGNABLE
 
 - (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated;
 
+/**
+    The zoom level of the receiver.
+    
+    In addition to affecting the visual size and detail of features on the map,
+    the zoom level affects the size of the vector tiles that are loaded. At zoom
+    level 0, each tile covers the entire world map; at zoom level 1, it covers ¼
+    of the world; at zoom level 2, <sup>1</sup>⁄<sub>16</sub> of the world, and
+    so on.
+ */
 @property (nonatomic) double zoomLevel;
 @property (nonatomic, readonly) double maximumZoomLevel;
 @property (nonatomic, readonly) double minimumZoomLevel;

platform/darwin/MGLGeometry_Private.h

@@ -1,5 +1,7 @@
 #import "MGLGeometry.h"
 
+#import <TargetConditionals.h>
+
 #import <mbgl/map/map.hpp>
 #import <mbgl/util/geo.hpp>
 
@@ -26,6 +28,12 @@ NS_INLINE BOOL MGLCoordinateInCoordinateBounds(CLLocationCoordinate2D coordinate
     return bounds.contains(MGLLatLngFromLocationCoordinate2D(coordinate));
 }
 
+#if TARGET_OS_MAC
 NS_INLINE mbgl::EdgeInsets MGLEdgeInsetsFromNSEdgeInsets(NSEdgeInsets insets) {
     return { insets.top, insets.left, insets.bottom, insets.right };
 }
+#elif TARGET_OS_IOS
+NS_INLINE mbgl::EdgeInsets MGLEdgeInsetsFromNSEdgeInsets(UIEdgeInsets insets) {
+    return { insets.top, insets.left, insets.bottom, insets.right };
+}
+#endif

platform/darwin/MGLMultiPoint_Private.h

@@ -21,16 +21,27 @@ NS_ASSUME_NONNULL_BEGIN
 - (instancetype)initWithCoordinates:(CLLocationCoordinate2D *)coords count:(NSUInteger)count;
 - (BOOL)intersectsOverlayBounds:(MGLCoordinateBounds)overlayBounds;
 
+/** Adds a shape annotation to the given vector by asking the delegate for style values. */
 - (void)addShapeAnnotationObjectToCollection:(std::vector<mbgl::ShapeAnnotation> &)shapes withDelegate:(id <MGLMultiPointDelegate>)delegate;
+
+/** Constructs a shape annotation properties object by asking the delegate for style values. */
 - (mbgl::ShapeAnnotation::Properties)shapeAnnotationPropertiesObjectWithDelegate:(id <MGLMultiPointDelegate>)delegate;
 
 @end
 
+/** An object that tells the MGLMultiPoint instance how to style itself. */
 @protocol MGLMultiPointDelegate <NSObject>
 
+/** Returns the fill alpha value for the given annotation. */
 - (double)alphaForShapeAnnotation:(MGLShape *)annotation;
+
+/** Returns the stroke color object for the given annotation. */
 - (mbgl::Color)strokeColorForShapeAnnotation:(MGLShape *)annotation;
+
+/** Returns the fill color object for the given annotation. */
 - (mbgl::Color)fillColorForPolygonAnnotation:(MGLPolygon *)annotation;
+
+/** Returns the stroke width object for the given annotation. */
 - (CGFloat)lineWidthForPolylineAnnotation:(MGLPolyline *)annotation;
 
 @end

platform/osx/src/MGLAccountManager.m

@@ -20,8 +20,6 @@
     }
 }
 
-// Can be called from any thread.
-//
 + (instancetype)sharedManager {
     static dispatch_once_t onceToken;
     static MGLAccountManager *_sharedManager;

platform/osx/src/MGLAccountManager_Private.h

@@ -2,9 +2,14 @@
 
 @interface MGLAccountManager (Private)
 
-/** Returns the shared instance of the `MGLAccountManager` class. */
+/**
+    Returns the shared instance of the `MGLAccountManager` class.
+ 
+    This method can be called from any thread.
+ */
 + (instancetype)sharedManager;
 
+/// The current global access token.
 @property (atomic) NSString *accessToken;
 
 @end

platform/osx/src/MGLAttributionButton.h

@@ -1,11 +1,15 @@
 #import <Cocoa/Cocoa.h>
 
+/// Button that looks like a hyperlink and opens a URL.
 @interface MGLAttributionButton : NSButton
 
+/// Returns an `MGLAttributionButton` instance with the given title and URL.
 - (instancetype)initWithTitle:(NSString *)title URL:(NSURL *)url;
 
+/// The URL to open and display as a tooltip.
 @property (nonatomic) NSURL *URL;
 
+/// Opens the URL.
 - (IBAction)openURL:(id)sender;
 
 @end

platform/osx/src/MGLAttributionButton.m

@@ -9,10 +9,12 @@
         self.bordered = NO;
         self.bezelStyle = NSRegularSquareBezelStyle;
         
+        // Start with a copyright symbol. The whole string will be mini.
         NSMutableAttributedString *attributedTitle = [[NSMutableAttributedString alloc] initWithString:@"© "
                                                                                             attributes:@{
             NSFontAttributeName: [NSFont systemFontOfSize:[NSFont systemFontSizeForControlSize:NSMiniControlSize]],
         }];
+        // Append the specified title, underlining it like a hyperlink.
         [attributedTitle appendAttributedString:
          [[NSAttributedString alloc] initWithString:title
                                          attributes:@{
@@ -36,6 +38,7 @@
 }
 
 - (void)resetCursorRects {
+    // The whole button gets a pointing hand cursor, just like a hyperlink.
     [self addCursorRect:self.bounds cursor:[NSCursor pointingHandCursor]];
 }
 

platform/osx/src/MGLCompassCell.h

@@ -1,5 +1,5 @@
 #import <Cocoa/Cocoa.h>
 
+/// Circular slider with an arrow pointing north.
 @interface MGLCompassCell : NSSliderCell
-
 @end

platform/osx/src/MGLCompassCell.m

@@ -5,7 +5,9 @@
 - (instancetype)init {
     if (self = [super init]) {
         self.sliderType = NSCircularSlider;
+        // A tick mark for each cardinal direction.
         self.numberOfTickMarks = 4;
+        // This slider goes backwards!
         self.minValue = -360;
         self.maxValue = 0;
     }
@@ -13,6 +15,7 @@
 }
 
 - (void)drawKnob:(NSRect)knobRect {
+    // Draw a red triangle pointing whichever way the slider is facing.
     NSBezierPath *trianglePath = [NSBezierPath bezierPath];
     [trianglePath moveToPoint:NSMakePoint(NSMinX(knobRect), NSMaxY(knobRect))];
     [trianglePath lineToPoint:NSMakePoint(NSMaxX(knobRect), NSMaxY(knobRect))];

platform/osx/src/MGLMapView+IBAdditions.m

@@ -33,6 +33,8 @@
 
 - (void)setLatitude:(double)latitude {
     if (!isnan(self.pendingLongitude)) {
+        // With both components present, set the real center coordinate and
+        // forget the pending parts.
         self.centerCoordinate = CLLocationCoordinate2DMake(latitude, self.pendingLongitude);
         self.pendingLatitude = NAN;
         self.pendingLongitude = NAN;
@@ -53,6 +55,8 @@
 
 - (void)setLongitude:(double)longitude {
     if (!isnan(self.pendingLatitude)) {
+        // With both components present, set the real center coordinate and
+        // forget the pending parts.
         self.centerCoordinate = CLLocationCoordinate2DMake(self.pendingLatitude, longitude);
         self.pendingLatitude = NAN;
         self.pendingLongitude = NAN;

platform/osx/src/MGLOpenGLLayer.h

@@ -4,6 +4,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/// A subclass of NSOpenGLLayer that creates the environment mbgl needs to
+/// render good-looking maps.
 @interface MGLOpenGLLayer : NSOpenGLLayer
 @end
 

platform/osx/src/NSBundle+MGLAdditions.h

@@ -8,6 +8,7 @@ void mgl_linkBundleCategory();
 
 @interface NSBundle (MGLAdditions)
 
+/// Returns the Mapbox.framework bundle.
 + (instancetype)mgl_frameworkBundle;
 
 @end

platform/osx/src/NSProcessInfo+MGLAdditions.h

@@ -4,6 +4,8 @@ void mgl_linkProcessInfoCategory();
 
 @interface NSProcessInfo (MGLAdditions)
 
+/// Returns YES if the current process is Interface Builder’s helper process for
+/// rendering designables.
 - (BOOL)mgl_isInterfaceBuilderDesignablesAgent;
 
 @end