add comments to public methods of MapboxMap and MapboxMapVisualizer classes

Author: brnkhy

Runtime/Mapbox/BaseModule/Map/MapboxMap.cs

@@ -9,6 +9,15 @@
 
 namespace Mapbox.BaseModule.Map
 {
+    /// <summary>
+    /// The primary object responsible for controlling and rendering the map.
+    /// </summary>
+    /// <remarks>
+    /// - <see cref="MapInformation"/>: Contains information about the map location, 
+    ///   detail level, and basic camera controls.
+    /// - <see cref="MapVisualizer"/>: Handles styling and visualization of the specified location.
+    /// - <see cref="MapService"/>: Manages interactions with the Mapbox API and data handling.
+    /// </remarks>
     [Serializable]
     public sealed class MapboxMap
     {
@@ -28,6 +37,10 @@ public MapboxMap(IMapInformation information, UnityContext unityContext, MapServ
             MapService = mapMapService;
         }
 
+        /// <summary>
+        /// Initialization method which organizes caches and object pool craeting, meta data loading etc.
+        /// </summary>
+        /// <returns></returns>
         public IEnumerator Initialize()
         {
             if (Status != InitializationStatus.WaitingForInitialization)
@@ -40,15 +53,30 @@ public IEnumerator Initialize()
 
             Status = InitializationStatus.Initialized;
             Initialized();
-            
         }
 
+        /// <summary>
+        /// Map update method, which we currently use per-frame, to recalculate the tile cover and run map visualizer on it.
+        /// </summary>
         public void MapUpdated()
         {
             MapService.TileCover(MapInformation, TileCover);
             MapVisualizer.Load(TileCover);
         }
 
+        /// <summary>
+        /// Provides a controlled method for jumping to specific locations on the map.
+        /// Unlike standard frame-by-frame map updates, this method ensures precise 
+        /// control over the transition process.
+        /// </summary>
+        /// <param name="callback">An optional callback method to execute upon completion.</param>
+        /// <remarks>
+        /// - Uses the location already in the settings, useful for initial map load then runtime location changes.
+        /// - Triggers events at the start and end of the loading process, useful for showing 
+        ///   or hiding a loading screen.
+        /// - Suspends per-frame map updates during the loading phase and resumes them 
+        ///   once loading is complete.
+        /// </remarks>
         public void LoadMapView(Action callback)
         {
             Status = InitializationStatus.LoadingView;
@@ -64,11 +92,25 @@ public void LoadMapView(Action callback)
             }));
         }
 
-        public void LoadMapView(Action callback, LatitudeLongitude coordinates)
+        /// <summary>
+        /// Provides a controlled method for jumping to specific locations on the map.
+        /// Unlike standard frame-by-frame map updates, this method ensures precise 
+        /// control over the transition process.
+        /// </summary>
+        /// <param name="targetLocation">The destination coordinates as a <see cref="LatitudeLongitude"/> instance.</param>
+        /// <param name="callback">An optional callback method to execute upon completion.</param>
+        /// <remarks>
+        /// - Takes a LatitudeLongitude for new map location.
+        /// - Triggers events at the start and end of the loading process, useful for showing 
+        ///   or hiding a loading screen.
+        /// - Suspends per-frame map updates during the loading phase and resumes them 
+        ///   once loading is complete.
+        /// </remarks>
+        public void LoadMapView(Action callback, LatitudeLongitude targetLocation)
         {
             Status = InitializationStatus.LoadingView;
             LoadViewStarting();
-            MapInformation.SetInformation(coordinates);
+            MapInformation.SetInformation(targetLocation);
             Runnable.Instance.StartCoroutine(LoadMapViewCoroutine(() =>
             {
                 MapService.TileCover(MapInformation, TileCover);
@@ -80,6 +122,23 @@ public void LoadMapView(Action callback, LatitudeLongitude coordinates)
             }));
         }
 
+        /// <summary>
+        /// Provides a controlled method for jumping to specific locations on the map.
+        /// Unlike standard frame-by-frame map updates, this method ensures precise 
+        /// control over the transition process.
+        /// 
+        /// </summary>
+        /// <param name="targetLocation">The destination coordinates as a <see cref="LatitudeLongitude"/> instance.</param>
+        /// <param name="callback">An optional callback method to execute upon completion.</param>
+        /// <returns>
+        /// An <see cref="IEnumerator"/> that can be used for coroutine-based execution.
+        /// This allows the loading process to be handled asynchronously.
+        /// </returns>
+        /// <remarks>
+        /// - Returns an IEnumerator to let developers create and control their own coroutine.
+        /// - Does not pause per-frame updates.
+        /// - Does not trigger start and finished events.
+        /// </remarks>
         public IEnumerator LoadMapViewCoroutine(Action callback)
         {
             var tileCover = new TileCover();
@@ -88,6 +147,14 @@ public IEnumerator LoadMapViewCoroutine(Action callback)
             callback();
         }
 
+        /// <summary>
+        /// Change the map core settings.
+        /// If the per-frame updates are enabled, new settings will be applied next frame.
+        /// </summary>
+        /// <param name="latlng">Location to show</param>
+        /// <param name="zoom">Zoom level of the map</param>
+        /// <param name="pitch">Pitch value of the camera</param>
+        /// <param name="bearing">Bearing value of the camera</param>
         public void ChangeView(LatitudeLongitude? latlng = null, float? zoom = null, float? pitch = null, float? bearing = null)
         {
             MapInformation.SetInformation(latlng, zoom, pitch, bearing);
@@ -101,10 +168,29 @@ public void OnDestroy()
 
         public void UpdateTileCover() => MapService.TileCover(MapInformation, TileCover);
 
+        /// <summary>
+        /// All modules are initialized, you can get&use any object and/or register to events safely.
+        /// </summary>
         public Action Initialized = () => {};
+        /// <summary>
+        /// Load view procedure is starting. Status is set to InitializationStatus.LoadingView and per-frame updates
+        /// are suspended until this procedure finishes.
+        /// </summary>
         public Action LoadViewStarting = () => { };
+        /// <summary>
+        /// Load view procedure is finished. Status is set to InitializationStatus.ReadyForUpdates and per-frame updates
+        /// will continue.
+        /// </summary>
         public Action LoadViewCompleted = () => { };
+        /// <summary>
+        /// Map tile finished loading with targeted detail level data. This tile isn't temporary anymore, it'll be in
+        /// ActiveTiles list.
+        /// </summary>
         public Action<UnityMapTile> TileLoaded = (tile) => { };
+        /// <summary>
+        /// Map tile unloading event fires for tiles that are still in active tiles list but not in the latest tileCover.
+        /// UnityMapTile object attached to event will be pooled after the event call.
+        /// </summary>
         public Action<UnityMapTile> TileUnloading = (tile) => { };
     }
 }

Runtime/Mapbox/BaseModule/Map/MapboxMapVisualizer.cs

@@ -10,6 +10,9 @@
 
 namespace Mapbox.BaseModule.Map
 {
+    /// <summary>
+    /// The primary object responsible for preparing the data and generating the visuals of the map.
+    /// </summary>
     [Serializable]
     public class MapboxMapVisualizer : IMapVisualizer
     {
@@ -45,13 +48,25 @@ public virtual IEnumerator Initialize()
             yield return LayerModules.Select(x => x.Initialize()).WaitForAll();
         }
 
+        /// <summary>
+        /// Prepare data and visuals for given tile cover. It loads the data to memory, generates vector feature visuals
+        /// and prepare it all to ensure following tile requests will be finished in single frame.
+        /// So this method doesn't create the tile, it prepares everything inside a tile.
+        /// </summary>
+        /// <param name="tileCover"></param>
+        /// <returns></returns>
         public virtual IEnumerator LoadTileCoverToMemory(TileCover tileCover)
         {
             var hashsetTiles = new HashSet<CanonicalTileId>(tileCover.Tiles.Select(x => x.Canonical));
             var coroutines = LayerModules.Select(x => x.LoadTiles(hashsetTiles));
             yield return coroutines.WaitForAll();
         }
 
+        /// <summary>
+        /// Create the map in given tileCover area. Makes decision to load or unload tiles and handle temporary filler
+        /// tiles until actual tiles are loaded.
+        /// </summary>
+        /// <param name="tileCover"></param>
         public virtual void Load(TileCover tileCover)
         {
             _tileCreatedThisFrame = 0;
@@ -102,6 +117,7 @@ public virtual void Load(TileCover tileCover)
 
             foreach (var tileId in _toRemove)
             {
+                //this tryget is unnecessary, just get it. it cannot not be there.
                 if (ActiveTiles.TryGetValue(tileId, out var tile))
                 {
                     TileUnloading(tile);
@@ -151,6 +167,15 @@ public void OnDestroy()
             }
         }
 
+        /// <summary>
+        /// Find a LayerModule by given type. LayerModules are kept as ILayerModule and this method queries by concrete
+        /// so it might cause unexpected issues if there are multiple layer modules of same type. This method will simply
+        /// return the first one found.
+        /// </summary>
+        /// <param name="type"></param>
+        /// <param name="module"></param>
+        /// <typeparam name="T"></typeparam>
+        /// <returns></returns>
         public bool TryGetLayerModule<T>(Type type, out T module) where T : ILayerModule
         {
             module = (T)LayerModules.FirstOrDefault(x => x.GetType() == type);
@@ -283,6 +308,11 @@ protected bool FinalizeTempTile(UnityMapTile unityMapTile)
             return tileFinished;
         }
 
+        /// <summary>
+        /// Triggers the repositioning for all tiles per module. This is necessary for vector module to move feature visuals
+        /// if (and only if) map settings are such that camera is static and map&tiles are moving (slippy map).
+        /// </summary>
+        /// <param name="mapInformation"></param>
         protected void RepositionAllTiles(IMapInformation mapInformation)
         {
             foreach (var tilePair in ActiveTiles)
@@ -296,7 +326,15 @@ protected void RepositionAllTiles(IMapInformation mapInformation)
             }
         }
 
+        /// <summary>
+        /// Map tile finished loading with targeted detail level data. This tile isn't temporary anymore, it'll be in
+        /// ActiveTiles list.
+        /// </summary>
         public event Action<UnityMapTile> TileLoaded = (tile) => { };
+        /// <summary>
+        /// Map tile unloading event fires for tiles that are still in active tiles list but not in the latest tileCover.
+        /// UnityMapTile object attached to event will be pooled after the event call.
+        /// </summary>
         public event Action<UnityMapTile> TileUnloading = (tile) => { };
     }
 }