utils inline docs

sdkproject/Assets/Mapbox/Core/Unity/Editor/GeocodeAttributeDrawer.cs

@@ -4,6 +4,11 @@ namespace Mapbox.Editor
     using UnityEditor;
     using Mapbox.Unity.Utilities;
 
+    /// <summary>
+    /// Custom property drawer for geocodes <para/>
+    /// Includes a search window to enable search of Lat/Lon via geocoder. 
+    /// Requires a Mapbox token be set for the project
+    /// </summary>
     [CustomPropertyDrawer(typeof(GeocodeAttribute))]
     public class GeocodeAttributeDrawer : PropertyDrawer
     {

sdkproject/Assets/Mapbox/Core/Unity/MapboxAccess.cs

@@ -9,11 +9,19 @@ namespace Mapbox.Unity
     using Mapbox.Platform;
     using Mapbox.Unity.Utilities;
 
+    /// <summary>
+    /// Object for retrieving an API token and making http requests.
+    /// Contains a lazy <see cref="T:Mapbox.Geocoding.Geocoder">Geocoder</see> and a lazy <see cref="T:Mapbox.Directions.Directions">Directions</see> for convenience.
+    /// </summary>
     public class MapboxAccess : IFileSource
     {
         readonly string _accessPath = Path.Combine(Application.streamingAssetsPath, Constants.Path.TOKEN_FILE);
 
         static MapboxAccess _instance = new MapboxAccess();
+
+        /// <summary>
+        /// The singleton instance.
+        /// </summary>
         public static MapboxAccess Instance
         {
             get
@@ -28,6 +36,10 @@ public static MapboxAccess Instance
             LoadAccessToken();
         }
 
+        /// <summary>
+        /// The Mapbox API access token. 
+        /// See <see href="https://www.mapbox.com/mapbox-unity-sdk/docs/01-mapbox-api-token.html">Mapbox API Congfiguration in Unity</see>.
+        /// </summary>
         string _accessToken;
         public string AccessToken
         {
@@ -53,6 +65,9 @@ void ValidateMapboxAccessFile()
             }
         }
 
+        /// <summary>
+        /// Loads the access token from <see href="https://docs.unity3d.com/Manual/StreamingAssets.html">StreamingAssets</see>.
+        /// </summary>
         void LoadAccessToken()
         {
 #if  UNITY_EDITOR || !UNITY_ANDROID
@@ -62,6 +77,9 @@ void LoadAccessToken()
 #endif
         }
 
+        /// <summary>
+        /// Android-specific token file loading.
+        /// </summary>
         IEnumerator LoadMapboxAccess()
         {
             var request = new WWW(_accessPath);
@@ -72,6 +90,12 @@ IEnumerator LoadMapboxAccess()
             AccessToken = request.text;
         }
 
+        /// <summary>
+        /// Makes an asynchronous url query.
+        /// </summary>
+        /// <returns>The request.</returns>
+        /// <param name="url">URL.</param>
+        /// <param name="callback">Callback.</param>
         public IAsyncRequest Request(string url, Action<Response> callback)
         {
             var uriBuilder = new UriBuilder(url);
@@ -97,10 +121,11 @@ public InvalidTokenException(string message) : base(message)
             }
         }
 
+        Geocoder _geocoder;
+
         /// <summary>
         /// Lazy geocoder.
         /// </summary>
-        Geocoder _geocoder;
         public Geocoder Geocoder
         {
             get
@@ -113,10 +138,11 @@ public Geocoder Geocoder
             }
         }
 
+        Directions _directions;
+
         /// <summary>
         /// Lazy Directions.
         /// </summary>
-        Directions _directions;
         public Directions Directions
         {
             get

sdkproject/Assets/Mapbox/Core/Unity/Utilities/Conversions.cs

@@ -48,6 +48,21 @@ private static Vector2d LatLonToMeters(double lat, double lon)
             return new Vector2d((float)posx, (float)posy);
         }
 
+        /// <summary>
+        /// Converts WGS84 lat/lon to x/y meters in reference to a center point
+        /// </summary>
+        /// <param name="lat"> The latitude. </param>
+        /// <param name="lon"> The longitude. </param>
+        /// <param name="refPoint"> A <see cref="T:UnityEngine.Vector2d"/> center point to offset resultant xy</param>
+        /// <param name="scale"> Scale in meters. (default scale = 1) </param>
+        /// <returns> A <see cref="T:UnityEngine.Vector2d"/> xy tile ID. </returns>
+        /// <example>
+        /// Converts a Lat/Lon of (37.7749, 122.4194) into Unity coordinates for a map centered at (10,10) and a scale of 2.5 meters for every 1 Unity unit 
+        /// <code>
+        /// var worldPosition = Conversions.GeoToWorldPosition(37.7749, 122.4194, new Vector2d(10, 10), (float)2.5);
+        /// // worldPosition = ( 11369163.38585, 34069138.17805 )
+        /// </code>
+        /// </example>
         public static Vector2d GeoToWorldPosition(double lat, double lon, Vector2d refPoint, float scale = 1)
         {
             var posx = lon * OriginShift / 180;
@@ -56,8 +71,8 @@ public static Vector2d GeoToWorldPosition(double lat, double lon, Vector2d refPo
             return new Vector2d((posx - refPoint.x) * scale, (posy - refPoint.y) * scale);
         }
 
-        public static Vector2d GeoToWorldPosition(Vector2d latLong, Vector2d refPoint, float scale = 1)
-        {
+        public static Vector2d GeoToWorldPosition(Vector2d latLong, Vector2d refPoint, float scale = 1)
+        {
             return GeoToWorldPosition(latLong.x, latLong.y, refPoint, scale);
         }
 
@@ -67,6 +82,15 @@ public static Vector2d GeoToWorldPosition(Vector2d latLong, Vector2d refPoint, f
         /// </summary>
         /// <param name="m"> A <see cref="T:UnityEngine.Vector2d"/> of coordinates in meters.  </param>
         /// <returns> The <see cref="T:Mapbox.Utils.Vector2d"/> in lat/lon. </returns>
+
+        /// <example>
+        /// Converts EPSG:900913 xy meter coordinates to lat lon 
+        /// <code>
+        /// var worldPosition =  new Vector2d (4547675.35434,13627665.27122);
+        /// var latlon = Conversions.MetersToLatLon(worldPosition);
+        /// // latlon = ( 37.77490, 122.41940 )
+        /// </code>
+        /// </example>
         public static Vector2d MetersToLatLon(Vector2d m)
         {
             var vx = (m.x / OriginShift) * 180;
@@ -81,6 +105,15 @@ public static Vector2d MetersToLatLon(Vector2d m)
         /// <param name="m"> <see cref="T:UnityEngine.Vector2d"/> XY coords in meters. </param>
         /// <param name="zoom"> Zoom level. </param>
         /// <returns> A <see cref="T:UnityEngine.Vector2d"/> xy tile ID. </returns>
+        /// 
+        /// <example>
+        /// Converts EPSG:900913 xy meter coordinates to web mercator tile XY coordinates at zoom 12.
+        /// <code>
+        /// var meterXYPosition = new Vector2d (4547675.35434,13627665.27122);
+        /// var tileXY = Conversions.MetersToTile (meterXYPosition, 12);
+        /// // tileXY = ( 655, 2512 )
+        /// </code>
+        /// </example>
         public static Vector2 MetersToTile(Vector2d m, int zoom)
         {
             var p = MetersToPixels(m, zoom);

sdkproject/Assets/Mapbox/Core/Unity/Utilities/GeocodeAttribute.cs

@@ -2,6 +2,11 @@
 {
     using UnityEngine;
 
+	/// <summary>
+	///     Property attribute used to create custom Geocode GUI field<para/>
+	///     Links to custom drawer: 
+	///     <see cref="T:Mapbox.Editor.GeocodeAttributeDrawer"/>. 
+	/// </summary>
 	public class GeocodeAttribute : PropertyAttribute
 	{
 

sdkproject/Assets/Mapbox/Core/Unity/Utilities/VectorExtensions.cs

@@ -11,47 +11,118 @@ namespace Mapbox.Unity.Utilities
 
     public static class VectorExtensions
     {
+        /// <summary>
+        /// Vector2 convenience method to convert Vector2 to Vector3.
+        /// </summary>
+        /// <returns>Vector3 with a y value of zero.</returns>
+        /// <param name="v">Vector2.</param>
         public static Vector3 ToVector3xz(this Vector2 v)
         {
             return new Vector3(v.x, 0, v.y);
         }
 
+        /// <summary>
+        /// Vector2d convenience method to convert Vector2d to Vector3.
+        /// </summary>
+        /// <returns>Vector3 with a y value of zero.</returns>
+        /// <param name="v">Vector2d.</param>
         public static Vector3 ToVector3xz(this Vector2d v)
         {
             return new Vector3((float)v.x, 0, (float)v.y);
         }
 
+        /// <summary>
+        /// Vector3 convenience method to convert Vector3 to Vector2.
+        /// </summary>
+        /// <returns>The Vector2.</returns>
+        /// <param name="v">Vector3.</param>
         public static Vector2 ToVector2xz(this Vector3 v)
         {
-            return new Vector3(v.x, v.z);
+            return new Vector2(v.x, v.z);
         }
 
+        /// <summary>
+        /// Vector3 convenience method to convert Vector3 to Vector2d.
+        /// </summary>
+        /// <returns>The Vector2d.</returns>
+        /// <param name="v">Vector3.</param>
         public static Vector2d ToVector2d(this Vector3 v)
         {
             return new Vector2d(v.x, v.z);
         }
 
+        /// <summary>
+        /// Transform extension method to move a Unity transform to a specific latitude/longitude.
+        /// </summary>
+        /// <param name="t">Transform.</param>
+        /// <param name="lat">Latitude.</param>
+        /// <param name="lng">Longitude.</param>
+        /// <param name="refPoint">Reference point.</param>
+        /// <param name="scale">Scale.</param>
+        /// <example>
+        /// Place a Unity transform at 10, 10, with a map center of (0, 0) and scale 1:
+        /// <code>
+        /// transform.MoveToGeocoordinate(10, 10, new Vector2d(0, 0), 1f);
+        /// Debug.Log(transform.position);
+        /// // (1113195.0, 0.0, 1118890.0)
+        /// </code>
+        /// </example>
         public static void MoveToGeocoordinate(this Transform t, double lat, double lng, Vector2d refPoint, float scale = 1)
         {
             t.position = Conversions.GeoToWorldPosition(lat, lng, refPoint, scale).ToVector3xz();
         }
 
+        /// <summary>
+        /// Transform extension method to move a Unity transform to a specific Vector2d.
+        /// </summary>
+        /// <param name="t">Transform.</param>
+        /// <param name="latLon">Latitude Longitude.</param>
+        /// <param name="refPoint">Reference point.</param>
+        /// <param name="scale">Scale.</param>
+        /// <example>
+        /// Place a Unity transform at 10, 10, with a map center of (0, 0) and scale 1:
+        /// <code>
+        /// transform.MoveToGeocoordinate(new Vector2d(10, 10), new Vector2d(0, 0), 1f);
+        /// Debug.Log(transform.position);
+        /// // (1113195.0, 0.0, 1118890.0)
+        /// </code>
+        /// </example>
         public static void MoveToGeocoordinate(this Transform t, Vector2d latLon, Vector2d refPoint, float scale = 1)
         {
             t.MoveToGeocoordinate(latLon.x, latLon.y, refPoint, scale);
         }
 
+        /// <summary>
+        /// Vector2 extension method to convert from a latitude/longitude to a Unity Vector3.
+        /// </summary>
+        /// <returns>The Vector3 Unity position.</returns>
+        /// <param name="latLon">Latitude Longitude.</param>
+        /// <param name="refPoint">Reference point.</param>
+        /// <param name="scale">Scale.</param>
         public static Vector3 AsUnityPosition(this Vector2 latLon, Vector2d refPoint, float scale = 1)
         {
             return Conversions.GeoToWorldPosition(latLon.x, latLon.y, refPoint, scale).ToVector3xz();
         }
 
+        /// <summary>
+        /// Transform extension method to return the transform's position as a Vector2d latitude/longitude.
+        /// </summary>
+        /// <returns>Vector2d that represents latitude/longitude.</returns>
+        /// <param name="t">T.</param>
+        /// <param name="refPoint">Reference point.</param>
+        /// <param name="scale">Scale.</param>
+        /// <example>
+        /// Get the latitude/longitude of a transform at (1113195, 0, 1118890), map center (0, 0) and scale 1.
+        /// <code>
+        /// var latLng = transform.GetGeoPosition(new Vector2d(0, 0), 1);
+        /// Debug.Log(latLng);
+        /// // (10.00000, 10.00000)
+        /// </code>
+        /// </example>
         public static Vector2d GetGeoPosition(this Transform t, Vector2d refPoint, float scale = 1)
         {
             var pos = refPoint + (t.position / scale).ToVector2d();
             return Conversions.MetersToLatLon(pos);
         }
-
-        // TODO: add ability to get geo position from a vector2 or vector 3, as well (not just transform).
     }
 }