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

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java

@@ -6,10 +6,12 @@
 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 @@ protected MapView getMapView() {
     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 int compareTo(@NonNull Annotation 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) {

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);
-  }
 }

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() {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java

@@ -806,7 +806,7 @@ public void onClick(DialogInterface dialog, int which) {
   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>

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java

@@ -96,6 +96,9 @@ void initialise(@NonNull Context context, @NonNull MapboxMapOptions options) {
     setStyleUrl(options);
   }
 
+  /**
+   * Called when the hosting Activity/Fragment onStart() method is called.
+   */
   void onStart() {
     nativeMapView.update();
     trackingSettings.onStart();
@@ -105,10 +108,18 @@ void onStart() {
     }
   }
 
+  /**
+   * 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 @@ void onSaveInstanceState(Bundle outState) {
     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 @@ void onPostMapReady() {
   }
 
   /**
-   * 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 void setFocalBearing(double bearing, float focalX, float focalY, long dur
     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 @@ private void setStyleUrl(@NonNull MapboxMapOptions options) {
   /**
    * 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 String getStyleUrl() {
    * 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 Marker addMarker(@NonNull MarkerOptions markerOptions) {
    * 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,26 +1094,25 @@ public Marker addMarker(@NonNull BaseMarkerOptions markerOptions) {
    * 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
   public MarkerView addMarker(@NonNull BaseMarkerViewOptions markerOptions) {
     return annotationManager.addMarker(markerOptions, this, null);
   }
 
-
   /**
    * <p>
    * Adds a marker 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.
    *
-   * @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 MarkerView addMarker(@NonNull BaseMarkerViewOptions markerOptions,
   }
 
   /**
-   * 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 List<MarkerView> addMarkerViews(@NonNull List<? extends
   }
 
   /**
-   * 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 List<MarkerView> getMarkerViewsInRect(@NonNull RectF rect) {
    * 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 List<Marker> addMarkers(@NonNull List<? extends
    * 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 void updateMarker(@NonNull Marker updatedMarker) {
   /**
    * 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,20 +1228,19 @@ public Polygon addPolygon(@NonNull PolygonOptions polygonOptions) {
   /**
    * 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
   public List<Polygon> addPolygons(@NonNull List<PolygonOptions> polygonOptionsList) {
     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 void updatePolygon(Polygon polygon) {
    * <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 void removeMarker(@NonNull Marker marker) {
    * <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 void removePolyline(@NonNull Polyline polyline) {
    * <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 OnInfoWindowLongClickListener getOnInfoWindowLongClickListener() {
     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 void setOnMyBearingTrackingModeChangeListener(@Nullable OnMyBearingTracki
    * 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) {

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;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java

@@ -3,8 +3,9 @@
 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> {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java

@@ -15,7 +15,7 @@
 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>
  */

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java

@@ -3,7 +3,7 @@
 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>
  */