8322 javadoc 5.0.0 release (#8438)

* [android] - update javadoc 5.0.0 release

* update annotation and sources package javadoc

* update javadoc on MapboxMap and MapView

11 files changed, 97 insertions, 53 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java
index 831c1db5a3..a588ff6d23 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java
@@ -6,10 +6,12 @@ import com.mapbox.mapboxsdk.maps.MapView;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 
 /**
- * Annotation is an overlay on top of a {@link MapView},
- * from which {@link Polygon}, {@link Polyline} and {@link Marker} are derived.
+ * Annotation is an overlay on top of a Map.
  * <p>
- * it manages attachment to a map and identification, but does not require
+ * Known subclasses are {@link Polygon}, {@link Polyline} and {@link Marker}.
+ * </p>
+ * <p>
+ * This class manages attachment to a map and identification, but does not require
  * content to be placed at a geographical point.
  * </p>
  */
@@ -96,6 +98,12 @@ public abstract class Annotation implements Comparable<Annotation> {
     return mapView;
   }
 
+  /**
+   * Compares this Annotation object with another Annotation.
+   *
+   * @param annotation Another Annotation to compare with this object.
+   * @return returns 0 if id's match, 1 if id is lower, -1 if id is higher of another Annotation
+   */
   @Override
   public int compareTo(@NonNull Annotation annotation) {
     if (id < annotation.getId()) {
@@ -107,12 +115,10 @@ public abstract class Annotation implements Comparable<Annotation> {
   }
 
   /**
-   * Compares this {@link PolylineOptions} object with another {@link PolylineOptions} and
-   * determines if their color, alpha, width, and vertices match.
+   * Checks if this Annotation object is equal to another Annotation.
    *
-   * @param object Another {@link PolylineOptions} to compare with this object.
-   * @return True if color, alpha, width, and vertices match this {@link PolylineOptions} object.
-   * Else, false.
+   * @param object Another Annotation to check equality with this object.
+   * @return returns true both id's match else returns false.
    */
   @Override
   public boolean equals(Object object) {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java
index be2b586683..0d16c53b86 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java
@@ -1,22 +1,11 @@
 package com.mapbox.mapboxsdk.exceptions;
 
 /**
- * Thrown on conversion errors
+ * A ConversionException is thrown when a conversion failed to execute.
  */
 public class ConversionException extends RuntimeException {
 
-  public ConversionException() {
-  }
-
   public ConversionException(String detailMessage) {
     super(detailMessage);
   }
-
-  public ConversionException(String detailMessage, Throwable throwable) {
-    super(detailMessage, throwable);
-  }
-
-  public ConversionException(Throwable throwable) {
-    super(throwable);
-  }
 }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java
index bd24379af3..f0f9b9236b 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java
@@ -1,5 +1,8 @@
 package com.mapbox.mapboxsdk.exceptions;
 
+/**
+ * A InvalidMarkerPositionException is thrown when a Marker object is created with an invalid LatLng position.
+ */
 public class InvalidMarkerPositionException extends RuntimeException {
 
   public InvalidMarkerPositionException() {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
index 51566a6587..8c8b70d788 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
@@ -806,7 +806,7 @@ public class MapView extends FrameLayout {
   public static final int DID_FINISH_RENDERING_FRAME = 9;
 
   /**
-   * This event is triggered when the map finished rendeirng the frame fully.
+   * This event is triggered when the map finished rendering the frame fully.
    * <p>
    * Register to {@link MapChange} events with {@link MapView#addOnMapChangedListener(OnMapChangedListener)}.
    * </p>
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
index 5d2c649d32..6edae8b944 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
@@ -96,6 +96,9 @@ public final class MapboxMap {
     setStyleUrl(options);
   }
 
+  /**
+   * Called when the hosting Activity/Fragment onStart() method is called.
+   */
   void onStart() {
     nativeMapView.update();
     trackingSettings.onStart();
@@ -105,10 +108,18 @@ public final class MapboxMap {
     }
   }
 
+  /**
+   * Called when the hosting Activity/Fragment onStop() method is called.
+   */
   void onStop() {
     trackingSettings.onStop();
   }
 
+  /**
+   * Called when the hosting Activity/Fragment is going to be destroyed and map state needs to be saved.
+   *
+   * @param outState the bundle to save the state to.
+   */
   void onSaveInstanceState(Bundle outState) {
     outState.putParcelable(MapboxConstants.STATE_CAMERA_POSITION, transform.getCameraPosition());
     outState.putBoolean(MapboxConstants.STATE_DEBUG_ACTIVE, nativeMapView.getDebug());
@@ -117,6 +128,11 @@ public final class MapboxMap {
     uiSettings.onSaveInstanceState(outState);
   }
 
+  /**
+   * Called when the hosting Activity/Fragment is recreated and map state needs to be restored.
+   *
+   * @param savedInstanceState the bundle containing the saved state
+   */
   void onRestoreInstanceState(Bundle savedInstanceState) {
     final CameraPosition cameraPosition = savedInstanceState.getParcelable(MapboxConstants.STATE_CAMERA_POSITION);
     if (cameraPosition != null) {
@@ -153,13 +169,16 @@ public final class MapboxMap {
   }
 
   /**
-   * Called when the user
+   * Called when the region is changing or has changed.
    */
   void onUpdateRegionChange() {
     trackingSettings.update();
     annotationManager.update();
   }
 
+  /**
+   * Called when the map frame is fully rendered.
+   */
   void onUpdateFullyRendered() {
     CameraPosition cameraPosition = transform.invalidateCameraPosition();
     if (cameraPosition != null) {
@@ -819,10 +838,20 @@ public final class MapboxMap {
     transform.setBearing(bearing, focalX, focalY, duration);
   }
 
+  /**
+   * Returns the measured height of the Map.
+   *
+   * @return the height of the map
+   */
   public float getHeight() {
     return nativeMapView.getHeight();
   }
 
+  /**
+   * Returns the measured width of the Map.
+   *
+   * @return the width of the map
+   */
   public float getWidth() {
     return nativeMapView.getWidth();
   }
@@ -1014,7 +1043,7 @@ public final class MapboxMap {
   /**
    * Returns the map style currently displayed in the map view.
    *
-   * @return The URL of the map style.
+   * @return The URL of the map style
    */
   @UiThread
   @Nullable
@@ -1033,8 +1062,8 @@ public final class MapboxMap {
    * The marker's icon is rendered on the map at the location {@code Marker.position}.
    * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
    *
-   * @param markerOptions A marker options object that defines how to render the marker.
-   * @return The {@code Marker} that was added to the map.
+   * @param markerOptions A marker options object that defines how to render the marker
+   * @return The {@code Marker} that was added to the map
    */
   @UiThread
   @NonNull
@@ -1049,8 +1078,8 @@ public final class MapboxMap {
    * The marker's icon is rendered on the map at the location {@code Marker.position}.
    * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
    *
-   * @param markerOptions A marker options object that defines how to render the marker.
-   * @return The {@code Marker} that was added to the map.
+   * @param markerOptions A marker options object that defines how to render the marker
+   * @return The {@code Marker} that was added to the map
    */
   @UiThread
   @NonNull
@@ -1065,8 +1094,8 @@ public final class MapboxMap {
    * The marker's icon is rendered on the map at the location {@code Marker.position}.
    * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
    *
-   * @param markerOptions A marker options object that defines how to render the marker.
-   * @return The {@code Marker} that was added to the map.
+   * @param markerOptions A marker options object that defines how to render the marker
+   * @return The {@code Marker} that was added to the map
    */
   @UiThread
   @NonNull
@@ -1074,7 +1103,6 @@ public final class MapboxMap {
     return annotationManager.addMarker(markerOptions, this, null);
   }
 
-
   /**
    * <p>
    * Adds a marker to this map.
@@ -1082,9 +1110,9 @@ public final class MapboxMap {
    * The marker's icon is rendered on the map at the location {@code Marker.position}.
    * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
    *
-   * @param markerOptions             A marker options object that defines how to render the marker.
-   * @param onMarkerViewAddedListener Callback invoked when the View has been added to the map.
-   * @return The {@code Marker} that was added to the map.
+   * @param markerOptions             A marker options object that defines how to render the marker
+   * @param onMarkerViewAddedListener Callback invoked when the View has been added to the map
+   * @return The {@code Marker} that was added to the map
    */
   @UiThread
   @NonNull
@@ -1094,7 +1122,14 @@ public final class MapboxMap {
   }
 
   /**
-   * FIXME javadoc
+   * Adds multiple markersViews to this map.
+   * <p>
+   * The marker's icon is rendered on the map at the location {@code Marker.position}.
+   * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
+   * </p>
+   *
+   * @param markerViewOptions A list of markerView options objects that defines how to render the markers
+   * @return A list of the {@code MarkerView}s that were added to the map
    */
   @UiThread
   @NonNull
@@ -1104,7 +1139,10 @@ public final class MapboxMap {
   }
 
   /**
-   * FIXME javadoc
+   * Returns markerViews found inside of a rectangle on this map.
+   *
+   * @param rect the rectangular area on the map to query for markerViews
+   * @return A list of the markerViews that were found in the rectangle
    */
   @UiThread
   @NonNull
@@ -1119,8 +1157,8 @@ public final class MapboxMap {
    * The marker's icon is rendered on the map at the location {@code Marker.position}.
    * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
    *
-   * @param markerOptionsList A list of marker options objects that defines how to render the markers.
-   * @return A list of the {@code Marker}s that were added to the map.
+   * @param markerOptionsList A list of marker options objects that defines how to render the markers
+   * @return A list of the {@code Marker}s that were added to the map
    */
   @UiThread
   @NonNull
@@ -1134,7 +1172,7 @@ public final class MapboxMap {
    * Updates a marker on this map. Does nothing if the marker isn't already added.
    * </p>
    *
-   * @param updatedMarker An updated marker object.
+   * @param updatedMarker An updated marker object
    */
   @UiThread
   public void updateMarker(@NonNull Marker updatedMarker) {
@@ -1144,8 +1182,8 @@ public final class MapboxMap {
   /**
    * Adds a polyline to this map.
    *
-   * @param polylineOptions A polyline options object that defines how to render the polyline.
-   * @return The {@code Polyine} that was added to the map.
+   * @param polylineOptions A polyline options object that defines how to render the polyline
+   * @return The {@code Polyine} that was added to the map
    */
   @UiThread
   @NonNull
@@ -1190,8 +1228,8 @@ public final class MapboxMap {
   /**
    * Adds multiple polygons to this map.
    *
-   * @param polygonOptionsList A list of polygon options objects that defines how to render the polygons.
-   * @return A list of the {@code Polygon}s that were added to the map.
+   * @param polygonOptionsList A list of polygon options objects that defines how to render the polygons
+   * @return A list of the {@code Polygon}s that were added to the map
    */
   @UiThread
   @NonNull
@@ -1199,11 +1237,10 @@ public final class MapboxMap {
     return annotationManager.addPolygons(polygonOptionsList, this);
   }
 
-
   /**
    * Update a polygon on this map.
    *
-   * @param polygon An updated polygon object.
+   * @param polygon An updated polygon object
    */
   @UiThread
   public void updatePolygon(Polygon polygon) {
@@ -1214,7 +1251,7 @@ public final class MapboxMap {
    * <p>
    * Convenience method for removing a Marker from the map.
    * </p>
-   * Calls removeAnnotation() internally
+   * Calls removeAnnotation() internally.
    *
    * @param marker Marker to remove
    */
@@ -1227,7 +1264,7 @@ public final class MapboxMap {
    * <p>
    * Convenience method for removing a Polyline from the map.
    * </p>
-   * Calls removeAnnotation() internally
+   * Calls removeAnnotation() internally.
    *
    * @param polyline Polyline to remove
    */
@@ -1240,7 +1277,7 @@ public final class MapboxMap {
    * <p>
    * Convenience method for removing a Polygon from the map.
    * </p>
-   * Calls removeAnnotation() internally
+   * Calls removeAnnotation() internally.
    *
    * @param polygon Polygon to remove
    */
@@ -1620,6 +1657,11 @@ public final class MapboxMap {
     return annotationManager.getInfoWindowManager().getOnInfoWindowLongClickListener();
   }
 
+  /**
+   * Set an callback to be invoked when an InfoWindow closes.
+   *
+   * @param listener callback invoked when an InfoWindow closes
+   */
   public void setOnInfoWindowCloseListener(@Nullable OnInfoWindowCloseListener listener) {
     annotationManager.getInfoWindowManager().setOnInfoWindowCloseListener(listener);
   }
@@ -1719,7 +1761,6 @@ public final class MapboxMap {
    * Takes a snapshot of the map.
    *
    * @param callback Callback method invoked when the snapshot is taken.
-   * @param bitmap   A pre-allocated bitmap.
    */
   @UiThread
   public void snapshot(@NonNull SnapshotReadyCallback callback) {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/package-info.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/package-info.java
new file mode 100644
index 0000000000..85950735ef
--- /dev/null
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Contains the Mapbox Maps Android Storage API classes.
+ */
+package com.mapbox.mapboxsdk.storage;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java
index 27a3d5c898..1a1711e547 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java
@@ -3,8 +3,9 @@ package com.mapbox.mapboxsdk.style.sources;
 import java.util.HashMap;
 
 /**
- * Options for the {@link GeoJsonSource}
+ * Builder class for composing GeoJsonSource objects.
  *
+ * @see GeoJsonSource
  * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson">The online documentation</a>
  */
 public class GeoJsonOptions extends HashMap<String, Object> {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
index 9f957e7727..b253595713 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
@@ -15,7 +15,7 @@ import java.util.HashMap;
 import java.util.List;
 
 /**
- * A GeoJson source. Exposes a {@link FeatureCollection} from Json.
+ * GeoJson source, allows using FeatureCollections from Json.
  *
  * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson">the style specification</a>
  */
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
index eabbdb8395..98b74afcff 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
@@ -3,7 +3,7 @@ package com.mapbox.mapboxsdk.style.sources;
 import java.net.URL;
 
 /**
- * Raster Source enables the use of raster tiles.
+ * Raster source, allows using raster tiles as source.
  *
  * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-raster">The style specification</a>
  */
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java
index 9f403c2fb9..54e4e5f5d3 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java
@@ -8,7 +8,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * Tile set
+ * Tile set, allows using TileJson specification as source.
  *
  * @see <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">The tileset specification</a>
  */
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
index 68eb81b7f4..cff5ab6353 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
@@ -14,7 +14,7 @@ import java.util.Arrays;
 import java.util.List;
 
 /**
- * Vector source enables the use of vector tiles.
+ * Vector source, allows the use of vector tiles.
  *
  * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-vector">the style specification</a>
  */