cherry-picked 7013 into master (#7247)

1 files changed, 53 insertions, 34 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java
index 72037c2565..a32186b52e 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java
@@ -8,13 +8,20 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 
 /**
- * MarkerView is an annotation that shows an View at a geographical location.
+ * MarkerView is an annotation that shows a {@link android.view.View} at a geographical location. The
+ * default marker uses a provided icon. This icon can be customized using {@link IconFactory} to
+ * generate an {@link Icon} using a provided image. MarkerViews are added to the map by first giving
+ * a {@link LatLng} and using {@link MapboxMap#addMarker(BaseMarkerViewOptions)}. The marker view icon
+ * by default is anchored at the center bottom.
  * <p>
- * This class uses {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter} to adapt a
+ * If many markers are needed to be displayed on the map at once we suggest using {@link Marker}
+ * instead. This class uses {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter} to adapt a
  * MarkerView model to an Android SDK {@link android.view.View} object.
  * </p>
  * <p>
- * An {@link InfoWindow} can be shown when a MarkerView is pressed
+ * MarkerViews are designed to be interactive. They receive click events by default, and are often
+ * used with event listeners to bring up info windows. An {@link InfoWindow} is displayed by default
+ * when either a title or snippet is provided.
  * </p>
  */
 public class MarkerView extends Marker {
@@ -85,14 +92,14 @@ public class MarkerView extends Marker {
     }
 
     /**
-     * Specifies the anchor being set on a particular point point of the MarkerView.
+     * Specifies the anchor being set on a particular point of the MarkerView.
      * <p>
      * The anchor point is specified in the continuous space [0.0, 1.0] x [0.0, 1.0], where (0, 0)
      * is the top-left corner of the image, and (1, 1) is the bottom-right corner.
      * </p>
      *
-     * @param u u-coordinate of the anchor, as a ratio of the image width (in the range [0, 1])
-     * @param v v-coordinate of the anchor, as a ratio of the image height (in the range [0, 1])
+     * @param u u-coordinate of the anchor, as a ratio of the image width (in the range [0, 1]).
+     * @param v v-coordinate of the anchor, as a ratio of the image height (in the range [0, 1]).
      */
     public void setAnchor(@FloatRange(from = 0.0, to = 1.0) float u, @FloatRange(from = 0.0, to = 1.0) float v) {
         this.anchorU = u;
@@ -103,7 +110,7 @@ public class MarkerView extends Marker {
     /**
      * Get the horizontal distance, normalized to [0, 1], of the anchor from the left edge.
      *
-     * @return the u-value of the anchor
+     * @return The u-value of the anchor.
      */
     public float getAnchorU() {
         return anchorU;
@@ -112,7 +119,7 @@ public class MarkerView extends Marker {
     /**
      * Get the vertical distance, normalized to [0, 1], of the anchor from the top edge.
      *
-     * @return the v-value of the anchor
+     * @return the v-value of the anchor.
      */
     public float getAnchorV() {
         return anchorV;
@@ -124,8 +131,8 @@ public class MarkerView extends Marker {
      * These are calculated based on the View bounds and the provided anchor.
      * </p>
      *
-     * @param x the x-value of the offset
-     * @param y the y-value of the offset
+     * @param x the x-value of the offset.
+     * @param y the y-value of the offset.
      */
     void setOffset(float x, float y) {
         offsetX = x;
@@ -133,18 +140,18 @@ public class MarkerView extends Marker {
     }
 
     /**
-     * Internal method to get the horizontal calculated offset
+     * Internal method to get the horizontal calculated offset.
      *
-     * @return the calculated horizontal offset
+     * @return the calculated horizontal offset.
      */
     float getOffsetX() {
         return offsetX;
     }
 
     /**
-     * Internal method to get the vertical calculated offset
+     * Internal method to get the vertical calculated offset.
      *
-     * @return the calculated vertical offset
+     * @return the calculated vertical offset.
      */
     float getOffsetY() {
         return offsetY;
@@ -153,14 +160,15 @@ public class MarkerView extends Marker {
     /**
      * Specifies the anchor point of the info window on the View of the MarkerView.
      * <p>
-     * This is specified in the same coordinate system as the anchor.
+     * The anchor point is specified in the continuous space [0.0, 1.0] x [0.0, 1.0], where (0, 0)
+     * is the top-left corner of the image, and (1, 1) is the bottom-right corner.
      * </p>
      * <p>
      * The default is the top middle of the View.
      * </p>
      *
-     * @param u u-coordinate of the info window anchor, as a ratio of the image width (in the range [0, 1])
-     * @param v v-coordinate of the info window anchor, as a ratio of the image height (in the range [0, 1])
+     * @param u u-coordinate of the info window anchor, as a ratio of the image width (in the range [0, 1]).
+     * @param v v-coordinate of the info window anchor, as a ratio of the image height (in the range [0, 1]).
      * @see #setAnchor(float, float) for more details.
      */
     public void setInfoWindowAnchor(@FloatRange(from = 0.0, to = 1.0) float u, @FloatRange(from = 0.0, to = 1.0) float v) {
@@ -189,16 +197,17 @@ public class MarkerView extends Marker {
     /**
      * Get the flat state of a MarkerView.
      *
-     * @return true is the MarkerView is flat; false is the MarkerView is billboard
+     * @return true if the MarkerView is flat; false if the MarkerView is billboard.
      */
     public boolean isFlat() {
         return flat;
     }
 
     /**
-     * Sets whether this marker should be flat against the map true or a billboard facing the camera false.
+     * Sets whether this MarkerView should be flat against the map (true) or a billboard facing the
+     * camera (false).
      *
-     * @param flat the flat state of the MarkerView
+     * @param flat the flat state of the MarkerView.
      */
     public void setFlat(boolean flat) {
         this.flat = flat;
@@ -207,7 +216,7 @@ public class MarkerView extends Marker {
     /**
      * Internal method to get the current tilted value of a MarkerView.
      *
-     * @return the tilted value
+     * @return the tilted value.
      */
     float getTilt() {
         return tiltValue;
@@ -216,7 +225,7 @@ public class MarkerView extends Marker {
     /**
      * Internal method to set the current titled value of a MarkerView.
      *
-     * @param tiltValue the tilted value to set
+     * @param tiltValue the tilted value to set.
      */
     void setTilt(@FloatRange(from = 0.0, to = MapboxConstants.MAXIMUM_TILT) float tiltValue) {
         this.tiltValue = tiltValue;
@@ -225,7 +234,7 @@ public class MarkerView extends Marker {
     /**
      * Set the visible state of a MarkerView.
      *
-     * @param visible true will make the MarkerView visible, false will hide the MarkerViews
+     * @param visible true will make the MarkerView visible, false will hide the MarkerView.
      */
     public void setVisible(boolean visible) {
         this.visible = visible;
@@ -237,7 +246,7 @@ public class MarkerView extends Marker {
     /**
      * Returns the visible state of the MarkerView.
      *
-     * @return the visible state
+     * @return the visible state.
      */
     public boolean isVisible() {
         return visible;
@@ -246,14 +255,14 @@ public class MarkerView extends Marker {
     /**
      * Set the rotation value of the MarkerView in degrees.
      * <p>
-     * Input will be limited to 0 - 360 degrees
+     * Input will be limited to 0 - 360 degrees.
      * </p>
      * <p>
      * This will result in animating the rotation of the MarkerView using an rotation animator
      * from current value to the provided parameter value.
      * </p>
      *
-     * @param rotation the rotation value to animate to
+     * @param rotation the rotation value to animate to.
      */
     public void setRotation(float rotation) {
         // limit to 0 - 360 degrees
@@ -274,7 +283,7 @@ public class MarkerView extends Marker {
     /**
      * Get the rotation value of the MarkerView.
      *
-     * @return the rotation value
+     * @return the rotation value.
      */
     public float getRotation() {
         return rotation;
@@ -283,7 +292,7 @@ public class MarkerView extends Marker {
     /**
      * Get the alpha value of the MarkerView.
      *
-     * @return the alpha value
+     * @return the alpha value.
      */
     public float getAlpha() {
         return alpha;
@@ -296,7 +305,7 @@ public class MarkerView extends Marker {
      * from current value to the provided parameter value.
      * </p>
      *
-     * @param alpha the alpha value to animate to
+     * @param alpha the alpha value to animate to.
      */
     public void setAlpha(@FloatRange(from = 0.0, to = 255.0) float alpha) {
         this.alpha = alpha;
@@ -308,7 +317,7 @@ public class MarkerView extends Marker {
     /**
      * Set the icon of the MarkerView.
      *
-     * @param icon the icon to be used as Marker image
+     * @param icon the {@link Icon} to be used as Marker image.
      */
     @Override
     public void setIcon(@Nullable Icon icon) {
@@ -323,6 +332,11 @@ public class MarkerView extends Marker {
         super.setIcon(transparentIcon);
     }
 
+    /**
+     * Sets the location of the marker.
+     *
+     * @param position A {@link LatLng} defining the marker position.
+     */
     @Override
     public void setPosition(LatLng position) {
         super.setPosition(position);
@@ -331,6 +345,11 @@ public class MarkerView extends Marker {
         }
     }
 
+    /**
+     * Determine if the {@link MarkerView} is selected or not.
+     *
+     * @return True if the MarkerView's selected, else false.
+     */
     public boolean isSelected() {
         return selected;
     }
@@ -345,7 +364,7 @@ public class MarkerView extends Marker {
     /**
      * Get the icon of the MarkerView.
      *
-     * @return the icon use as Marker image
+     * @return the icon use as Marker image.
      */
     @Override
     public Icon getIcon() {
@@ -361,12 +380,12 @@ public class MarkerView extends Marker {
      * This method is used to notify that a MarkerView is no longer active by setting a null value.
      * </p>
      *
-     * @param mapboxMap the MapboxMap instances
+     * @param mapboxMap the MapboxMap instances.
      */
     @Override
     public void setMapboxMap(MapboxMap mapboxMap) {
         super.setMapboxMap(mapboxMap);
-        if(mapboxMap!=null) {
+        if (mapboxMap != null) {
             if (isFlat()) {
                 // initial tilt value if MapboxMap is started with a tilt attribute
                 tiltValue = (float) mapboxMap.getCameraPosition().tilt;
@@ -379,7 +398,7 @@ public class MarkerView extends Marker {
     /**
      * Get the String representation of a MarkerView.
      *
-     * @return the String representation
+     * @return the String representation.
      */
     @Override
     public String toString() {