From 73324ae2f886ac32fc673c996b00faf0383d93c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= <mxn@1ec5.org>
Date: Wed, 2 Dec 2015 15:08:51 -0800
Subject: [PATCH] [osx] Commented private headers and implementation files

---
 include/mbgl/osx/MGLMapView+IBAdditions.h     | 37 ++++++++++++++++++-
 include/mbgl/osx/MGLMapView.h                 |  9 +++++
 platform/darwin/MGLGeometry_Private.h         |  8 ++++
 platform/darwin/MGLMultiPoint_Private.h       | 11 ++++++
 platform/osx/src/MGLAccountManager.m          |  2 -
 platform/osx/src/MGLAccountManager_Private.h  |  7 +++-
 platform/osx/src/MGLAttributionButton.h       |  4 ++
 platform/osx/src/MGLAttributionButton.m       |  3 ++
 platform/osx/src/MGLCompassCell.h             |  2 +-
 platform/osx/src/MGLCompassCell.m             |  3 ++
 platform/osx/src/MGLMapView+IBAdditions.m     |  4 ++
 platform/osx/src/MGLOpenGLLayer.h             |  2 +
 platform/osx/src/NSBundle+MGLAdditions.h      |  1 +
 platform/osx/src/NSProcessInfo+MGLAdditions.h |  2 +
 14 files changed, 89 insertions(+), 6 deletions(-)

diff --git a/include/mbgl/osx/MGLMapView+IBAdditions.h b/include/mbgl/osx/MGLMapView+IBAdditions.h
index 8dacd5ec7..b524328c5 100644
--- a/include/mbgl/osx/MGLMapView+IBAdditions.h
+++ b/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
diff --git a/include/mbgl/osx/MGLMapView.h b/include/mbgl/osx/MGLMapView.h
index 32f068a4c..a604a7951 100644
--- a/include/mbgl/osx/MGLMapView.h
+++ b/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;
diff --git a/platform/darwin/MGLGeometry_Private.h b/platform/darwin/MGLGeometry_Private.h
index 936695fec..08d1ad369 100644
--- a/platform/darwin/MGLGeometry_Private.h
+++ b/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
diff --git a/platform/darwin/MGLMultiPoint_Private.h b/platform/darwin/MGLMultiPoint_Private.h
index e0d875d88..c1f1fa158 100644
--- a/platform/darwin/MGLMultiPoint_Private.h
+++ b/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
diff --git a/platform/osx/src/MGLAccountManager.m b/platform/osx/src/MGLAccountManager.m
index 14969c101..f3a2fce7c 100644
--- a/platform/osx/src/MGLAccountManager.m
+++ b/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;
diff --git a/platform/osx/src/MGLAccountManager_Private.h b/platform/osx/src/MGLAccountManager_Private.h
index c0b8d2666..a918f2b2d 100644
--- a/platform/osx/src/MGLAccountManager_Private.h
+++ b/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
diff --git a/platform/osx/src/MGLAttributionButton.h b/platform/osx/src/MGLAttributionButton.h
index 7bc0fa535..9ff313784 100644
--- a/platform/osx/src/MGLAttributionButton.h
+++ b/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
diff --git a/platform/osx/src/MGLAttributionButton.m b/platform/osx/src/MGLAttributionButton.m
index 642f71f60..b14d36cff 100644
--- a/platform/osx/src/MGLAttributionButton.m
+++ b/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]];
 }
 
diff --git a/platform/osx/src/MGLCompassCell.h b/platform/osx/src/MGLCompassCell.h
index 8c89b43e1..5ed70dcb0 100644
--- a/platform/osx/src/MGLCompassCell.h
+++ b/platform/osx/src/MGLCompassCell.h
@@ -1,5 +1,5 @@
 #import <Cocoa/Cocoa.h>
 
+/// Circular slider with an arrow pointing north.
 @interface MGLCompassCell : NSSliderCell
-
 @end
diff --git a/platform/osx/src/MGLCompassCell.m b/platform/osx/src/MGLCompassCell.m
index 88911de2f..b3a4ad454 100644
--- a/platform/osx/src/MGLCompassCell.m
+++ b/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))];
diff --git a/platform/osx/src/MGLMapView+IBAdditions.m b/platform/osx/src/MGLMapView+IBAdditions.m
index 504bc789d..d6c6b40cb 100644
--- a/platform/osx/src/MGLMapView+IBAdditions.m
+++ b/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;
diff --git a/platform/osx/src/MGLOpenGLLayer.h b/platform/osx/src/MGLOpenGLLayer.h
index 9429b01bb..5c8ac43e9 100644
--- a/platform/osx/src/MGLOpenGLLayer.h
+++ b/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
 
diff --git a/platform/osx/src/NSBundle+MGLAdditions.h b/platform/osx/src/NSBundle+MGLAdditions.h
index 6d6ebc35a..642fcf141 100644
--- a/platform/osx/src/NSBundle+MGLAdditions.h
+++ b/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
diff --git a/platform/osx/src/NSProcessInfo+MGLAdditions.h b/platform/osx/src/NSProcessInfo+MGLAdditions.h
index 6b34f5475..cd5ec148e 100644
--- a/platform/osx/src/NSProcessInfo+MGLAdditions.h
+++ b/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