@nativescript-community/ui-mapbox 6.2.15 → 6.2.20

package/index.android.js

@@ -1,8 +1,14 @@
+/**
+ * Android Implementation
+ *
+ * @todo FIXME: The gcFix() implementation currently assumes only one map visible at a time.
+ */
 import { request } from '@nativescript-community/perms';
-import { AndroidApplication, Application, Color, File, Http, ImageSource, Trace, Utils, knownFolders, path } from '@nativescript/core';
+import { AndroidApplication, Application, Color, File, Http, Image, ImageSource, Trace, Utils, knownFolders, path } from '@nativescript/core';
 import { ExpressionParser } from './expression/expression-parser';
 import { Layer, LayerFactory } from './layers/layer-factory';
-import { CLog, CLogTypes, MapStyle, MapboxCommon, MapboxViewBase, telemetryProperty } from './common';
+import { CLog, CLogTypes, MapStyle, MapboxCommon, MapboxTraceCategory, MapboxViewBase, telemetryProperty } from './common';
+// Export the enums for devs not using TS
 export * from './common';
 function _getLocation(loc) {
     if (loc === null) {
@@ -41,17 +47,39 @@ export function setLogLevel(level) {
     }
     Logger.setVerbosity(loggingLevel);
 }
+/**
+ * A map view created in XML.
+ *
+ * This is the class that is created when the Mapbox XML tag
+ * is encountered while parsing a view.
+ *
+ * Angular components need to register the Mapbox tag as follows:
+ *
+ * import { registerElement } from "nativescript-angular/element-registry";
+ * registerElement( "Mapbox", () => require("nativescript-mapbox").MapboxView);
+ *
+ * The registerElement call is what binds the XML tag to the class that creates it.
+ *
+ * @see MapboxViewBase
+ */
 export class MapboxView extends MapboxViewBase {
     constructor() {
         super();
         this.settings = null;
+        // whether or not the view has already been initialized.
+        // see initNativeView()
         this.initialized = false;
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'constructor(): building new MapboxView object.');
         }
     }
+    /**
+     * programmatically include settings
+     */
     setConfig(settings) {
+        // zoom level is not applied unless center is set
         if (settings.zoomLevel && !settings.center) {
+            // Eiffel tower, Paris
             settings.center = {
                 lat: 48.858093,
                 lng: 2.294694
@@ -62,9 +90,36 @@ export class MapboxView extends MapboxViewBase {
     getNativeMapView() {
         return this.nativeMapView;
     }
+    /**
+     * Return the Mapbox() API Shim instance
+     *
+     * This returns a reference to the Mapbox API shim class instance.
+     * See class Mapbox below.
+     *
+     * @see Mapbox
+     */
     getMapboxApi() {
         return this.mapbox;
     }
+    /**
+     * Creates the native view.
+     *
+     * This method is supposed to create the native view. NativeScript caches
+     * and re-uses views to save on memory and increase performance. Unfortunately,
+     * the inner details of exactly how this is done is challenging to tease apart.
+     *
+     * The problem is that in order to create the Mapbox view we need the access token from
+     * the XML, but in the case of a pure NativeScript app with property binding
+     * (see the demo), the properties don't seem to be available until the page is loaded.
+     *
+     * As a workaround, I wait until the page is loaded to configure the map. See initNativeView.
+     *
+     * It seems to me there should be a better way.
+     *
+     * @link https://docs.nativescript.org/core-concepts/properties#views-lifecycle-and-recycling
+     *
+     * @todo check this.
+     */
     createNativeView() {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'createNativeView(): top');
@@ -90,28 +145,56 @@ export class MapboxView extends MapboxViewBase {
             CLog(CLogTypes.info, 'initNativeView(): top');
         }
         this.nativeView.owner = this;
+        // Application.android.on(AndroidApplication.activityStartedEvent, this.onStart, this);
         Application.android.on(AndroidApplication.activityPausedEvent, this.onPause, this);
         Application.android.on(AndroidApplication.activityResumedEvent, this.onResume, this);
+        // Application.android.on(AndroidApplication.activityStartedEvent, this.onStop, this);
         super.initNativeView();
     }
+    /**
+     * when the view is destroyed.
+     *
+     * This is called by the framework when the view is actually destroyed.
+     * NativeScript, by design, tries to cache native views because
+     * creating native views is expensive.
+     *
+     * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+     */
     disposeNativeView() {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'disposeNativeView(): top');
         }
         this.nativeView.owner = null;
+        // Application.android.off(AndroidApplication.activityStartedEvent, this.onStart, this);
         Application.android.off(AndroidApplication.activityPausedEvent, this.onPause, this);
         Application.android.off(AndroidApplication.activityResumedEvent, this.onResume, this);
+        // Application.android.off(AndroidApplication.activityStartedEvent, this.onStop, this);
         if (this.mapbox) {
             this.mapbox.destroy();
         }
         super.disposeNativeView();
     }
+    /**
+     * initialize the map
+     *
+     * This method creates a new mapbox API instance and, through the show() method of the Mapbox API,
+     * creates a Mapbox native map view.
+     *
+     * @see show()
+     *
+     * @link https://docs.nativescript.org/core-concepts/events
+     *
+     * @todo FIXME: this.nativeMapView is unused and never actually set to anything.
+     */
     initMap() {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, "MapboxView:initMap(): top - accessToken is '" + this.config.accessToken + "'", this.config);
         }
         if (!this.nativeMapView && ((this.config && this.config.accessToken) || (this.settings && this.settings.accessToken))) {
             this.mapbox = new Mapbox(this);
+            // the NativeScript contentview class extends from Observable to provide the notify method
+            // which is the glue that joins this code with whatever callbacks are set in the Mapbox XML
+            // tag describing the map.
             const options = {
                 context: this._context,
                 parentView: this.nativeView,
@@ -223,6 +306,16 @@ export class MapboxView extends MapboxViewBase {
         }
     }
 }
+/**
+ * A NativeScript shim for the Mapbox API.
+ *
+ * This implements a Typescript shim over the Native Mapbox GL Android API.
+ *
+ * It is created in one of two ways:
+ *
+ * - directly via let mapbox = new Mapbox(); mapbox.show( ... )
+ * - via the Mapbox XML tag in which case a MapboxView object is created which hosts a reference to this class. (See MapboxView::getMapboxAPI())
+ */
 export class Mapbox extends MapboxCommon {
     constructor(view) {
         super(view);
@@ -233,7 +326,9 @@ export class Mapbox extends MapboxCommon {
         this._markers = [];
         this._polylines = [];
         this._polygons = [];
+        // list of polylines
         this.lines = [];
+        // registered callbacks.
         this.eventCallbacks = {};
         this._markerIconDownloadCache = [];
         this.iconCache = {};
@@ -245,7 +340,29 @@ export class Mapbox extends MapboxCommon {
             CLog(CLogTypes.info, 'constructor(): end of Mapbox constructor.');
         }
     }
+    /**
+     * not used
+     */
     setMapboxViewInstance(mapboxViewInstance) { }
+    /**
+     * show the map programmatically.
+     *
+     * This method is used to programmatically display a map. It is also called
+     * by the MapboxView::init() method which initializes the map when the Mapbox
+     * XML tags is encountered
+     *
+     * options may additionally include:
+     *
+     * - context
+     * - parentView
+     * - onLocationPermissionGranted
+     * - onLocationPermissionDenied
+     * - onMapReady
+     *
+     * @see MapboxView::init()
+     *
+     * @todo FIXME: the timeout delay before showing the map works around some race condition. The source error needs to be figured out.
+     */
     show(options) {
         return new Promise((resolve, reject) => {
             try {
@@ -254,10 +371,14 @@ export class Mapbox extends MapboxCommon {
                     if (Trace.isEnabled()) {
                         CLog(CLogTypes.info, 'show()');
                     }
+                    // if no accessToken was set the app may crash.
+                    //
+                    // FIXME: Even if using a local server add some string.
                     if (settings.accessToken === undefined) {
                         reject('mapbox_accesstoken_missing');
                         return;
                     }
+                    // if already added, make sure it's removed first
                     if (this._mapboxViewInstance) {
                         if (Trace.isEnabled()) {
                             CLog(CLogTypes.info, 'show(): view already created. Removing it.');
@@ -275,10 +396,20 @@ export class Mapbox extends MapboxCommon {
                     if (settings.context) {
                         context = settings.context;
                     }
+                    // Per the Mapbox Android Native samples:
+                    //
+                    // "Mapbox access token is configured here. This needs to be called either in your application
+                    // object or in the same activity which contains the mapview."
                     com.mapbox.mapboxsdk.Mapbox.getInstance(context, this._accessToken);
                     const mapboxMapOptions = this._getMapboxMapOptions(settings);
+                    // unlike the Mapbox Android Native samples, we are not laying the map out
+                    // using the Android XML layout features. Instead, we are creating the map
+                    // programmatically.
                     this._mapboxViewInstance = new com.mapbox.mapboxsdk.maps.MapView(context, mapboxMapOptions);
+                    // required per the Mapbox Android API.
                     this._mapboxViewInstance.onCreate(null);
+                    // define some listeners to inform in case the map does not
+                    // load.
                     if (Trace.isEnabled()) {
                         this.onDidFailLoadingMapListener = new com.mapbox.mapboxsdk.maps.MapView.OnDidFailLoadingMapListener({
                             onDidFailLoadingMap: (error) => CLog(CLogTypes.error, 'Mapbox::show(): failed to load map:', error)
@@ -297,16 +428,21 @@ export class Mapbox extends MapboxCommon {
                             if (Trace.isEnabled()) {
                                 CLog(CLogTypes.info, 'show(): onMapReady() with instance:', this._mapboxMapInstance);
                             }
+                            // Android SDK 7.0.0 and on requires that the style be set separately after the map
+                            // is initialized. We do not consider the map ready until the style has successfully
+                            // loaded.
                             this.setMapStyle(settings.style).then((style) => {
                                 if (Trace.isEnabled()) {
                                     CLog(CLogTypes.info, 'show(): style loaded.');
                                 }
+                                // initialize the event handlers now that we have a constructed view.
                                 this.initEventHandlerShim(settings, this._mapboxViewInstance);
                                 this._addMarkers(settings.markers, this._mapboxViewInstance);
                                 if (settings.showUserLocation) {
                                     this.requestFineLocationPermission()
                                         .then(() => {
                                         this.showUserLocationMarker(settings.locationComponentOptions);
+                                        // if we have a callback defined, call it.
                                         if (settings.onLocationPermissionGranted) {
                                             settings.onLocationPermissionGranted(this._mapboxMapInstance);
                                         }
@@ -317,6 +453,7 @@ export class Mapbox extends MapboxCommon {
                                         }
                                     });
                                 }
+                                // if we have an onMapReady callback fire it.
                                 if (settings.onMapReady) {
                                     settings.onMapReady(this._mapboxMapInstance);
                                 }
@@ -330,6 +467,8 @@ export class Mapbox extends MapboxCommon {
                     if (Trace.isEnabled()) {
                         CLog(CLogTypes.info, 'show(): after getMapAsync()');
                     }
+                    // we either have been given a view to add the map to or we
+                    // add it to the top making it full screen.
                     if (settings.parentView) {
                         if (Trace.isEnabled()) {
                             CLog(CLogTypes.info, 'show(): adding map to passed in view');
@@ -340,6 +479,7 @@ export class Mapbox extends MapboxCommon {
                         if (Trace.isEnabled()) {
                             CLog(CLogTypes.info, 'show(): adding map to passed in container');
                         }
+                        // Application.android.currentContext has been removed.
                         context = Application.android.foregroundActivity;
                         if (!context) {
                             context = Application.android.startActivity;
@@ -358,6 +498,7 @@ export class Mapbox extends MapboxCommon {
                         CLog(CLogTypes.info, 'show(): showIt() bottom');
                     }
                 };
+                // FIXME: There is some initialization error. A short delay works around this.
                 setTimeout(showIt, settings.delay ? settings.delay : 200);
             }
             catch (ex) {
@@ -368,6 +509,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * hide the map
+     */
     hide() {
         return new Promise((resolve, reject) => {
             try {
@@ -406,6 +550,11 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * destroy the map programmatically
+     *
+     * Destroy the map instance.
+     */
     destroy(nativeMap) {
         return new Promise(async (resolve, reject) => {
             this.clearEventListeners();
@@ -425,6 +574,10 @@ export class Mapbox extends MapboxCommon {
                 this.symbolManager.onDestroy();
                 this.symbolManager = null;
             }
+            // if we have a location marker we need to disable it before destroying the map
+            //
+            // This is here to prevent a crash. The user code should disable/re-enable the
+            // location marker.
             if (this._locationComponent) {
                 if (Trace.isEnabled()) {
                     CLog(CLogTypes.info, 'destroy(): Location marker not disabled before destroy() called.');
@@ -442,6 +595,7 @@ export class Mapbox extends MapboxCommon {
                 this._mapboxViewInstance.onPause();
                 this._mapboxViewInstance.onStop();
                 this._mapboxViewInstance.destroyDrawingCache();
+                // let the API know that we're programmatically destroying the map.
                 this._mapboxViewInstance.onDestroy();
                 this._mapboxViewInstance = null;
                 this._mapboxMapInstance = null;
@@ -449,6 +603,14 @@ export class Mapbox extends MapboxCommon {
             resolve();
         });
     }
+    /**
+     * Clear Event Listeners
+     *
+     * Explicitly clear all registered event listeners. It's not clear to me whether or not this
+     * is strictly necessary as I imagine these should all get cleaned up when the map is destroyed
+     * but given the complication of NativeScript's garbage collection scheme it seems like a good
+     * idea to remove these handlers explicitly.
+     */
     clearEventListeners() {
         if (this.onDidFailLoadingMapListener) {
             this._mapboxViewInstance.removeOnDidFailLoadingMapListener(this.onDidFailLoadingMapListener);
@@ -515,6 +677,9 @@ export class Mapbox extends MapboxCommon {
             this.onLocationClickListener = null;
         }
     }
+    // ------------------------------------------------
+    // Life Cycle Hooks
+    // ------------------------------------------------
     async onStart(nativeMap) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'onStart()');
@@ -551,6 +716,14 @@ export class Mapbox extends MapboxCommon {
         }
         this._mapboxViewInstance.onDestroy();
     }
+    /**
+     * event handler shim
+     *
+     * Initialize our event handler shim so that we can intercept events here.
+     *
+     * @param { any } settings
+     * @param { MapboxView } mapboxView
+     */
     initEventHandlerShim(settings, mapboxNativeViewInstance) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'Mapbox:initEventHandlerShim(): top');
@@ -581,6 +754,22 @@ export class Mapbox extends MapboxCommon {
             }
         }, mapboxNativeViewInstance);
     }
+    /**
+     * register on click handlers.
+     *
+     * The native mapbox API does not, apparently, support click handlers
+     * on circles, but it does for markers and polylines. WTF?
+     *
+     * Here we attempt to replicate the mapbox-gl-js behaviour of being
+     * able to assign an onClick handler to a layer by it's layer id.
+     *
+     * @param {string} event - the event to subscribe to. i.e. 'click'.
+     * @param {string} id - the id of the layer
+     * @param {function} callback - the callback to invoke when the layer is clicked on.
+     * @param {object] nativeMapView - reference to the native Map view.
+     *
+     * @link https://github.com/mapbox/mapbox-android-demo/issues/540
+     */
     onMapEvent(eventName, id, callback, nativeMapView) {
         if (typeof this.eventCallbacks[eventName] == 'undefined') {
             this.eventCallbacks[eventName] = [];
@@ -590,12 +779,21 @@ export class Mapbox extends MapboxCommon {
             callback
         });
     }
+    /**
+     * remove an event handler for a layer
+     *
+     * This will remove all event handlers (that we manage here) for
+     * the given layer id and event.
+     */
     offMapEvent(eventName, id, nativeMapView) {
         if (typeof this.eventCallbacks[eventName] == 'undefined') {
             return;
         }
         this.eventCallbacks[eventName] = this.eventCallbacks[eventName].filter((entry) => entry.id !== id);
     }
+    /**
+     * If click events registered and a feature found for the event, then fire listener.
+     */
     checkForClickEvent(point, nativeMap) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'Mapbox:checkForClickEvent(): got click event with point:', JSON.stringify(point));
@@ -611,6 +809,12 @@ export class Mapbox extends MapboxCommon {
         this.view && this.view.notify({ eventName: 'mapClick', object: this.view, point });
         return false;
     }
+    /**
+     * handles a line click event
+     *
+     * Given a click on a line overlay, find the id of the underlying line layer
+     * an invoke any registered callbacks.
+     */
     handleLineClickEvent(clickOverlay) {
         const lineEntry = this.lines.find((entry) => {
             if (Trace.isEnabled()) {
@@ -633,7 +837,7 @@ export class Mapbox extends MapboxCommon {
                 }
                 return entry.callback(lineEntry);
             }
-        }
+        } // end of for loop over events.
         return false;
     }
     hasFineLocationPermission() {
@@ -649,9 +853,30 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * Request fine locaion permission
+     *
+     * @link https://docs.mapbox.com/android/core/overview/#permissionsmanager
+     */
     async requestFineLocationPermission() {
         return request('location');
     }
+    /**
+     * set the map style
+     *
+     * The 7.X version of the SDK uses a builder class for forming
+     * URLs.
+     *
+     * NOTE: The style must be explicitly set using this method in the onMapReady() handler.
+     *
+     * @param {string | MapStyle } style - a style following the Mapbox style specification or a URL to a style.
+     * @param {any} nativeMapViewInstance - native map view (com.mapbox.mapboxsdk.maps.MapView)
+     *
+     * @see MapboxViewCommonBase:setMapStyle()
+     *
+     * @link https://docs.mapbox.com/android/api/map-sdk/7.1.2/com/mapbox/mapboxsdk/maps/Style.Builder.html
+     * @link https://docs.mapbox.com/android/api/map-sdk/7.1.2/com/mapbox/mapboxsdk/maps/MapboxMap.html#setStyle-java.lang.String-com.mapbox.mapboxsdk.maps.Style.OnStyleLoaded-
+     */
     setMapStyle(style, nativeMapViewInstance) {
         return new Promise((resolve, reject) => {
             try {
@@ -659,15 +884,31 @@ export class Mapbox extends MapboxCommon {
                 if (Trace.isEnabled()) {
                     CLog(CLogTypes.info, 'setMapStyle(): with style:', style);
                 }
+                // callback for when the style is successfully loaded.
                 this.onDidFinishLoadingStyleListener = new com.mapbox.mapboxsdk.maps.MapView.OnDidFinishLoadingStyleListener({
                     onDidFinishLoadingStyle: () => {
                         if (Trace.isEnabled()) {
                             CLog(CLogTypes.info, 'Mapbox:setMapStyle(): style loaded');
                         }
+                        // FIXME: now that the map is initialized and the style is loaded we can
+                        // create the annotation managers that allow us to (hopefully) reliably
+                        // receive events on lines
                         const nMapbox = this._mapboxMapInstance;
                         const nMapView = this._mapboxViewInstance;
                         const nStyle = nMapbox.getStyle();
                         this.lineManager = new com.mapbox.mapboxsdk.plugins.annotation.LineManager(nMapView, nMapbox, nStyle);
+                        // this.symbolManager = new com.mapbox.mapboxsdk.plugins.annotation.SymbolManager(nMapView, nMapbox, nStyle);
+                        // this.symbolManager.addClickListener(
+                        //     new com.mapbox.mapboxsdk.plugins.annotation.OnSymbolClickListener({
+                        //         onAnnotationClick: (marker: com.mapbox.mapboxsdk.plugins.annotation.Symbol) => {
+                        //             const cachedMarker = this._getClickedMarkerDetails(marker);
+                        //             if (cachedMarker && cachedMarker.onTap) {
+                        //                 cachedMarker.onTap(cachedMarker);
+                        //             }
+                        //             return false;
+                        //         },
+                        //     })
+                        // );
                         this.onAnnotationClickListener = new com.mapbox.mapboxsdk.plugins.annotation.OnAnnotationClickListener({
                             onAnnotationClick: (line) => {
                                 if (Trace.isEnabled()) {
@@ -682,6 +923,7 @@ export class Mapbox extends MapboxCommon {
                     }
                 });
                 this._mapboxViewInstance.addOnDidFinishLoadingStyleListener(this.onDidFinishLoadingStyleListener);
+                // callback if loading the style fails.
                 this.onDidFailLoadingMapListener = new com.mapbox.mapboxsdk.maps.MapView.OnDidFailLoadingMapListener({
                     onDidFailLoadingMap: (error) => {
                         if (Trace.isEnabled()) {
@@ -789,6 +1031,11 @@ export class Mapbox extends MapboxCommon {
             throw ex;
         }
     }
+    /**
+     *
+     * @deprecated
+     * @link https://github.com/mapbox/mapbox-plugins-android/tree/master/plugin-annotation
+     */
     _addMarkers(markers, nativeMap) {
         if (!markers) {
             if (Trace.isEnabled()) {
@@ -833,6 +1080,7 @@ export class Mapbox extends MapboxCommon {
             this.iconFactory = com.mapbox.mapboxsdk.annotations.IconFactory.getInstance(Application.android.context);
         }
         const iconFactory = this.iconFactory;
+        // if any markers need to be downloaded from the web they need to be available synchronously, so fetch them first before looping
         this._downloadMarkerImages(markers).then((updatedMarkers) => {
             for (const m in updatedMarkers) {
                 const marker = updatedMarkers[m];
@@ -842,14 +1090,15 @@ export class Mapbox extends MapboxCommon {
                 markerOptions.setSnippet(marker.subtitle);
                 markerOptions.setPosition(new com.mapbox.mapboxsdk.geometry.LatLng(parseFloat(marker.lat), parseFloat(marker.lng)));
                 if (marker.icon) {
+                    // for markers from url see UrlMarker in https://github.com/mapbox/mapbox-gl-native/issues/5370
                     if (marker.icon.startsWith('res://')) {
-                        let cached = this.iconCache[marker.iconPath];
+                        let cached = this.iconCache[marker.icon];
                         if (!cached) {
                             const resourcename = marker.icon.substring(6);
                             const res = Utils.ad.getApplicationContext().getResources();
                             const identifier = res.getIdentifier(resourcename, 'drawable', Utils.ad.getApplication().getPackageName());
                             if (identifier !== 0) {
-                                cached = this.iconCache[marker.iconPath] = iconFactory.fromResource(identifier);
+                                cached = this.iconCache[marker.icon] = iconFactory.fromResource(identifier);
                             }
                         }
                         if (cached) {
@@ -874,7 +1123,9 @@ export class Mapbox extends MapboxCommon {
                     let cached = this.iconCache[marker.iconPath];
                     if (!cached) {
                         const iconFullPath = path.join(knownFolders.currentApp().path, marker.iconPath.replace('~/', ''));
+                        // if the file doesn't exist the app will crash, so checking it
                         if (File.exists(iconFullPath)) {
+                            // could set width, height, retina, see https://github.com/Telerik-Verified-Plugins/Mapbox/pull/42/files?diff=unified&short_path=1c65267, but that's what the marker.icon param is for..
                             cached = this.iconCache[marker.iconPath] = iconFactory.fromPath(iconFullPath);
                         }
                     }
@@ -921,6 +1172,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     *
+     * @deprecated
+     */
     _removeMarkers(ids, nativeMap) {
         if (!this._mapboxMapInstance) {
             return;
@@ -933,6 +1188,7 @@ export class Mapbox extends MapboxCommon {
                 }
             }
         }
+        // remove markers from cache
         if (ids) {
             this._markers = this._markers.filter((marker) => ids.indexOf(marker.id) === -1);
         }
@@ -1053,6 +1309,11 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * get users current location
+     *
+     * @link https://docs.mapbox.com/android/api/map-sdk/9.0.0/com/mapbox/mapboxsdk/location/LocationComponent.html#getLastKnownLocation--
+     */
     getUserLocation() {
         return new Promise((resolve, reject) => {
             try {
@@ -1072,6 +1333,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * @link https://www.mapbox.com/android-docs/api/mapbox-java/libjava-geojson/3.4.1/com/mapbox/geojson/Feature.html
+     */
     queryRenderedFeatures(options) {
         return new Promise((resolve, reject) => {
             try {
@@ -1145,6 +1409,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     *
+     * @deprecated
+     */
     addPolygon(options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1160,6 +1428,7 @@ export class Mapbox extends MapboxCommon {
                 }
                 polygonOptions.fillColor(Mapbox.getAndroidColor(options.fillColor));
                 polygonOptions.alpha(options.fillOpacity === undefined ? 1 : options.fillOpacity);
+                // Note that the stroke is barely visible, see https://github.com/mapbox/mapbox-gl-native/issues/5676
                 if (options.strokeColor) {
                     polygonOptions.strokeColor(Mapbox.getAndroidColor(options.strokeColor));
                 }
@@ -1177,6 +1446,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     *
+     * @deprecated
+     */
     addPolyline(options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1186,7 +1459,7 @@ export class Mapbox extends MapboxCommon {
                     return;
                 }
                 const polylineOptions = new com.mapbox.mapboxsdk.annotations.PolylineOptions();
-                polylineOptions.width(options.width || 5);
+                polylineOptions.width(options.width || 5); // default 5
                 polylineOptions.color(Mapbox.getAndroidColor(options.color));
                 polylineOptions.alpha(options.opacity === undefined ? 1 : options.opacity);
                 for (const p in points) {
@@ -1287,6 +1560,14 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * set an on map click listener.
+     *
+     * The new Mapbox Native SDK allows for multiple listeners on an event and follows the standard
+     * pattern of returning 'true' when a handler has handled the event and others shouldn't.
+     *
+     * Not returning a boolean from the listener function will cause a crash.
+     */
     setOnMapClickListener(listener, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1351,15 +1632,15 @@ export class Mapbox extends MapboxCommon {
                     CLog(CLogTypes.info, 'setOnMoveBeginListener():');
                 }
                 this.onMoveListener = new com.mapbox.mapboxsdk.maps.MapboxMap.OnMoveListener({
-                    onMoveBegin: (detector) => {
+                    onMoveBegin: (detector /* MoveGestureDetector */) => {
                         const coordinate = this._mapboxMapInstance.getCameraPosition().target;
                         return listener({
                             lat: coordinate.getLatitude(),
                             lng: coordinate.getLongitude()
                         });
                     },
-                    onMove: (detector) => { },
-                    onMoveEnd: (detector) => { }
+                    onMove: (detector /* MoveGestureDetector */) => { },
+                    onMoveEnd: (detector /* MoveGestureDetector */) => { }
                 });
                 this._mapboxMapInstance.addOnMoveListener(this.onMoveListener);
                 resolve();
@@ -1383,9 +1664,9 @@ export class Mapbox extends MapboxCommon {
                     CLog(CLogTypes.info, 'setOnMoveEndListener():');
                 }
                 this.onMoveListener = new com.mapbox.mapboxsdk.maps.MapboxMap.OnMoveListener({
-                    onMoveBegin: (detector) => { },
-                    onMove: (detector) => { },
-                    onMoveEnd: (detector) => {
+                    onMoveBegin: (detector /* MoveGestureDetector */) => { },
+                    onMove: (detector /* MoveGestureDetector */) => { },
+                    onMoveEnd: (detector /* MoveGestureDetector */) => {
                         const coordinate = this._mapboxMapInstance.getCameraPosition().target;
                         return listener({
                             lat: coordinate.getLatitude(),
@@ -1414,16 +1695,17 @@ export class Mapbox extends MapboxCommon {
                 if (Trace.isEnabled()) {
                     CLog(CLogTypes.info, 'setOnScrollListener():');
                 }
+                // the 'onMove' event seems like the one closest to the iOS implementation
                 this.onScrollListener = new com.mapbox.mapboxsdk.maps.MapboxMap.OnMoveListener({
-                    onMoveBegin: (detector) => { },
-                    onMove: (detector) => {
+                    onMoveBegin: (detector /* MoveGestureDetector */) => { },
+                    onMove: (detector /* MoveGestureDetector */) => {
                         const coordinate = this._mapboxMapInstance.getCameraPosition().target;
                         return listener({
                             lat: coordinate.getLatitude(),
                             lng: coordinate.getLongitude()
                         });
                     },
-                    onMoveEnd: (detector) => { }
+                    onMoveEnd: (detector /* MoveGestureDetector */) => { }
                 });
                 this._mapboxMapInstance.addOnMoveListener(this.onScrollListener);
                 resolve();
@@ -1586,7 +1868,10 @@ export class Mapbox extends MapboxCommon {
                     .build();
                 const retinaFactor = Utils.layout.getDisplayDensity();
                 const offlineRegionDefinition = new com.mapbox.mapboxsdk.offline.OfflineTilePyramidRegionDefinition(styleURL, bounds, options.minZoom, options.maxZoom, retinaFactor);
-                const info = Object.assign({ name: options.name }, options.metadata);
+                const info = {
+                    name: options.name,
+                    ...options.metadata
+                };
                 const infoStr = new java.lang.String(JSON.stringify(info));
                 const encodedMetadata = infoStr.getBytes();
                 if (!this._accessToken && !options.accessToken) {
@@ -1602,9 +1887,14 @@ export class Mapbox extends MapboxCommon {
                         reject(error);
                     },
                     onCreate: (offlineRegion) => {
+                        // if (options.onCreate) {
+                        //   options.onCreate(offlineRegion);
+                        // }
                         offlineRegion.setDownloadState(com.mapbox.mapboxsdk.offline.OfflineRegion.STATE_ACTIVE);
+                        // Monitor the download progress using setObserver
                         offlineRegion.setObserver(new com.mapbox.mapboxsdk.offline.OfflineRegion.OfflineRegionObserver({
                             onStatusChanged: (status) => {
+                                // Calculate the download percentage and update the progress bar
                                 const percentage = status.getRequiredResourceCount() >= 0 ? (100.0 * status.getCompletedResourceCount()) / status.getRequiredResourceCount() : 0.0;
                                 if (options.onProgress) {
                                     options.onProgress({
@@ -1613,6 +1903,7 @@ export class Mapbox extends MapboxCommon {
                                         completed: status.getCompletedResourceCount(),
                                         expected: status.getRequiredResourceCount(),
                                         percentage: Math.round(percentage * 100) / 100,
+                                        // downloading: status.getDownloadState() == com.mapbox.mapboxsdk.offline.OfflineRegion.STATE_ACTIVE,
                                         complete: status.isComplete()
                                     });
                                 }
@@ -1720,8 +2011,10 @@ export class Mapbox extends MapboxCommon {
                                         },
                                         onDelete: () => {
                                             resolve();
+                                            // don't return, see note below
                                         }
                                     }));
+                                    // don't break the loop as there may be multiple packs with the same name
                                 }
                             }
                         }
@@ -1748,6 +2041,7 @@ export class Mapbox extends MapboxCommon {
     addExtrusion(options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
+                // Create fill extrusion layer
                 const fillExtrusionLayer = new com.mapbox.mapboxsdk.style.layers.FillExtrusionLayer('3d-buildings', 'composite');
                 fillExtrusionLayer.setSourceLayer('building');
                 fillExtrusionLayer.setFilter(com.mapbox.mapboxsdk.style.expressions.Expression.eq(com.mapbox.mapboxsdk.style.expressions.Expression.get('extrude'), 'true'));
@@ -1757,6 +2051,7 @@ export class Mapbox extends MapboxCommon {
                 props[1] = com.mapbox.mapboxsdk.style.layers.PropertyFactory.fillExtrusionHeight(com.mapbox.mapboxsdk.style.expressions.Expression.get('height'));
                 props[2] = com.mapbox.mapboxsdk.style.layers.PropertyFactory.fillExtrusionBase(com.mapbox.mapboxsdk.style.expressions.Expression.get('min_height'));
                 props[3] = com.mapbox.mapboxsdk.style.layers.PropertyFactory.fillExtrusionOpacity(com.mapbox.mapboxsdk.style.expressions.Expression.literal(0.6));
+                // Set data-driven styling properties
                 fillExtrusionLayer.setProperties(props);
                 this._mapboxMapInstance.getStyle().addLayer(fillExtrusionLayer);
                 resolve();
@@ -1769,6 +2064,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * update a geojson source
+     *
+     */
     updateSource(id, options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1801,6 +2100,14 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * add a geojson or vector source
+     *
+     * Add a source that can then be referenced in the style specification
+     * passed to addLayer().
+     *
+     * @link https://docs.mapbox.com/mapbox-gl-js/api/#map#addsource
+     */
     addSource(id, options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1879,6 +2186,7 @@ export class Mapbox extends MapboxCommon {
                         break;
                     }
                     case 'raster':
+                        // use Array.create because a marshal error throws on TileSet if options.tiles directly passed.
                         const tiles = Array.create(java.lang.String, options.tiles.length);
                         options.tiles.forEach((val, i) => (tiles[i] = val));
                         const tileSet = new com.mapbox.mapboxsdk.style.sources.TileSet('2.0.0', tiles);
@@ -1919,6 +2227,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * remove source by id
+     */
     removeSource(id, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1941,6 +2252,24 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * a rough analogue to the mapbox-gl-js addLayer() method
+     *
+     * It would be nice if this {N} API matched the mapbox-gl-js API which
+     * would make it much easier to share mapping applications between the web
+     * and {N} apps.
+     *
+     * This method accepts a Mapbox-GL-JS style specification JSON object with some
+     * limitations:
+     *
+     * - the source: must be a GeoJSON object, vector source definition, or an id of a source added via addSource()
+     * - only a subset of paint properties are available.
+     *
+     * @param {object} style - a style following the Mapbox style specification.
+     * @param {any} nativeMapView - native map view (com.mapbox.mapboxsdk.maps.MapView)
+     *
+     * @link https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers
+     */
     async addLayer(style, belowLayerId, nativeMap) {
         const theMap = nativeMap || this._mapboxMapInstance;
         if (!theMap) {
@@ -1961,6 +2290,13 @@ export class Mapbox extends MapboxCommon {
         }
         this._mapboxMapInstance.getStyle().addLayer(layer.getNativeInstance());
     }
+    /**
+     * remove layer by ID
+     *
+     * Removes a layer given a layer id
+     *
+     * @param {string} id
+     */
     async removeLayer(id, nativeMap) {
         const theMap = nativeMap || this._mapboxMapInstance;
         theMap.getStyle().removeLayer(id);
@@ -1968,6 +2304,19 @@ export class Mapbox extends MapboxCommon {
             CLog(CLogTypes.info, 'Mapbox:removeLayer(): after removing layer');
         }
     }
+    /**
+     * @deprecated
+     * Add a point to a line
+     *
+     * This method appends a point to a line and is useful for drawing a users track.
+     *
+     * @param {id} id - id of line to add a point to.
+     * @param {array} lnglat - [lng,lat] to append to the line.
+     *
+     * @link https://github.com/mapbox/mapbox-gl-native/issues/13983
+     * @link https://docs.mapbox.com/android/api/mapbox-java/libjava-geojson/3.0.1/com/mapbox/geojson/Feature.html#Feature--
+     * @link https://docs.oracle.com/javase/8/docs/api/java/util/List.html
+     */
     async addLinePoint(id, lnglat, sourceId, nativeMapView) {
         try {
             const sId = !!sourceId ? sourceId : id + '_source';
@@ -1999,6 +2348,7 @@ export class Mapbox extends MapboxCommon {
                 const layers = [];
                 if (options.clusters) {
                     for (let i = 0; i < options.clusters.length; i++) {
+                        // TODO also allow Color object
                         layers.push([options.clusters[i].points, new Color(options.clusters[i].color).android]);
                     }
                 }
@@ -2014,10 +2364,12 @@ export class Mapbox extends MapboxCommon {
                     com.mapbox.mapboxsdk.style.layers.PropertyFactory.circleBlur(new java.lang.Float(0.2))
                 ]);
                 unclustered.setFilter(com.mapbox.mapboxsdk.style.expressions.Expression.neq(com.mapbox.mapboxsdk.style.expressions.Expression.get('cluster'), true));
-                this._mapboxMapInstance.getStyle().addLayer(unclustered);
+                this._mapboxMapInstance.getStyle().addLayer(unclustered); // , "building");
                 for (let i = 0; i < layers.length; i++) {
+                    // Add some nice circles
                     const circles = new com.mapbox.mapboxsdk.style.layers.CircleLayer('cluster-' + i, options.name);
                     circles.setProperties([
+                        // com.mapbox.mapboxsdk.style.layers.PropertyFactory.iconImage("icon")
                         com.mapbox.mapboxsdk.style.layers.PropertyFactory.circleColor(layers[i][1]),
                         com.mapbox.mapboxsdk.style.layers.PropertyFactory.circleRadius(new java.lang.Float(22.0)),
                         com.mapbox.mapboxsdk.style.layers.PropertyFactory.circleBlur(new java.lang.Float(0.2))
@@ -2032,8 +2384,9 @@ export class Mapbox extends MapboxCommon {
                             com.mapbox.mapboxsdk.style.expressions.Expression.lt(pointCount, com.mapbox.mapboxsdk.style.expressions.Expression.literal(java.lang.Integer.valueOf(layers[i - 1][0])))
                         ]));
                     }
-                    this._mapboxMapInstance.getStyle().addLayer(circles);
+                    this._mapboxMapInstance.getStyle().addLayer(circles); // , "building");
                 }
+                // Add the count labels (note that this doesn't show.. #sad)
                 const count = new com.mapbox.mapboxsdk.style.layers.SymbolLayer('count', options.name);
                 count.setProperties([
                     com.mapbox.mapboxsdk.style.layers.PropertyFactory.textField(com.mapbox.mapboxsdk.style.expressions.Expression.get('point_count')),
@@ -2051,6 +2404,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * constantly center the map on the users location.
+     */
     trackUser(options, nativeMap) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'trackUser(): top');
@@ -2100,6 +2456,7 @@ export class Mapbox extends MapboxCommon {
             CLog(CLogTypes.info, '_getMapStyle(): top with input:', input);
         }
         const Style = com.mapbox.mapboxsdk.maps.Style;
+        // allow for a style URL to be passed
         if (input.startsWith('mapbox://styles') || input.startsWith('http://') || input.startsWith('https://')) {
             return input;
         }
@@ -2128,9 +2485,17 @@ export class Mapbox extends MapboxCommon {
             return Style.TRAFFIC_NIGHT;
         }
         else {
+            // default
             return Style.MAPBOX_STREETS;
         }
     }
+    /**
+     * Mapbox Map Options
+     *
+     * @link https://github.com/mapbox/mapbox-gl-native/wiki/Android-6.x-to-7.x-migration-guide
+     * @link https://github.com/mapbox/mapbox-gl-native/blob/master/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java
+     * @link https://docs.mapbox.com/android/api/map-sdk/7.1.2/com/mapbox/mapboxsdk/maps/MapboxMapOptions.html
+     */
     _getMapboxMapOptions(settings) {
         const mapboxMapOptions = new com.mapbox.mapboxsdk.maps.MapboxMapOptions()
             .compassEnabled(!settings.hideCompass)
@@ -2140,7 +2505,9 @@ export class Mapbox extends MapboxCommon {
             .zoomGesturesEnabled(!settings.disableZoom)
             .attributionEnabled(!settings.hideAttribution)
             .logoEnabled(!settings.hideLogo);
+        // zoomlevel is not applied unless center is set
         if (settings.zoomLevel && !settings.center) {
+            // Eiffel tower, Paris
             settings.center = {
                 lat: 48.858093,
                 lng: 2.294694
@@ -2154,6 +2521,11 @@ export class Mapbox extends MapboxCommon {
         }
         return mapboxMapOptions;
     }
+    /**
+     * convert string to camera mode constant.
+     *
+     * @link https://docs.mapbox.com/android/api/map-sdk/8.1.0/com/mapbox/mapboxsdk/location/modes/CameraMode.html
+     */
     _stringToCameraMode(mode) {
         const modeRef = com.mapbox.mapboxsdk.location.modes.CameraMode;
         switch (mode) {
@@ -2173,6 +2545,9 @@ export class Mapbox extends MapboxCommon {
                 return modeRef.TRACKING_GPS_NORTH;
         }
     }
+    /**
+     * convert string to render mode
+     */
     _stringToRenderMode(mode) {
         let renderMode;
         switch (mode) {
@@ -2209,7 +2584,7 @@ export class Mapbox extends MapboxCommon {
         return "NONE";
     }
     _fineLocationPermissionGranted() {
-        let hasPermission = android.os.Build.VERSION.SDK_INT < 23;
+        let hasPermission = android.os.Build.VERSION.SDK_INT < 23; // Android M. (6.0)
         if (!hasPermission) {
             hasPermission = com.mapbox.android.core.permissions.PermissionsManager.areLocationPermissionsGranted(Application.android.context);
         }
@@ -2232,6 +2607,33 @@ export class Mapbox extends MapboxCommon {
         const jsonObj = new org.json.JSONObject(jsonStr);
         return JSON.parse(jsonObj.toString());
     }
+    /**
+     * show a user location marker
+     *
+     * This method must not be called before location permissions have been granted.
+     *
+     * Supported options are:
+     *
+     * - foregroundTintColor
+     * - foregroundStaleTintColor
+     * - backgroundTintColor
+     * - bearingTintColor
+     * - elevation
+     * - accuracyColor
+     * - accuracyAlpha
+     * - useDefaultLocationEngine
+     * - renderMode
+     * - cameraMode
+     * - clickListener
+     * - cameraTrackingChangeListener
+     *
+     * @param {object} options
+     *
+     * @link https://github.com/mapbox/mapbox-android-demo/blob/master/MapboxAndroidDemo/src/main/java/com/mapbox/mapboxandroiddemo/examples/location/LocationComponentOptionsActivity.java
+     * @link https://developer.android.com/reference/android/graphics/Color
+     *
+     * @todo at least with simulated data, the location is only updated once hence adding support for forceLocation method.
+     */
     showUserLocationMarker(options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -2321,6 +2723,11 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * hide (destroy) the user location marker
+     *
+     * This method destroys the user location marker.
+     */
     hideUserLocationMarker(nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -2349,6 +2756,15 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * Change the mode of the user location marker
+     *
+     * Used to change the camera tracking and render modes of an existing
+     * marker.
+     *
+     * The marker must be configured using showUserLocationMarker before this method
+     * can called.
+     */
     changeUserLocationMarkerMode(renderModeString, cameraModeString, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -2387,6 +2803,13 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * force updating of user location
+     *
+     * This method forces the user location marker, if displayed, to move to a new location
+     *
+     * @todo figure out why the user location marker is not updating.
+     */
     forceUserLocationUpdate(location, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -2397,6 +2820,7 @@ export class Mapbox extends MapboxCommon {
                     reject('No location component has been loaded');
                     return;
                 }
+                // the location object needs to be converted into an android location
                 const nativeLocation = new android.location.Location('background');
                 nativeLocation.setLatitude(location.latitude);
                 nativeLocation.setLongitude(location.longitude);
@@ -2467,9 +2891,14 @@ export class Mapbox extends MapboxCommon {
     _getClickedMarkerDetails(clicked) {
         for (const m in this._markers) {
             const cached = this._markers[m];
-            if (cached.lat == clicked.getPosition().getLatitude() &&
+            if (
+            // eslint-disable-next-line eqeqeq
+            cached.lat == clicked.getPosition().getLatitude() &&
+                // eslint-disable-next-line eqeqeq
                 cached.lng == clicked.getPosition().getLongitude() &&
-                cached.title == clicked.getTitle() &&
+                // eslint-disable-next-line eqeqeq
+                cached.title == clicked.getTitle() && // == because of null vs undefined
+                // eslint-disable-next-line eqeqeq
                 cached.subtitle == clicked.getSnippet()) {
                 return cached;
             }
@@ -2477,11 +2906,13 @@ export class Mapbox extends MapboxCommon {
     }
     _downloadImage(marker) {
         return new Promise((resolve, reject) => {
+            // to cache..
             if (this._markerIconDownloadCache[marker.icon]) {
                 marker.iconDownloaded = this._markerIconDownloadCache[marker.icon];
                 resolve(marker);
                 return;
             }
+            // ..or not to cache
             Http.getImage(marker.icon).then((output) => {
                 marker.iconDownloaded = output.android;
                 this._markerIconDownloadCache[marker.icon] = marker.iconDownloaded;