From 6cfee1db7cade57fcf3a9d4a6dfbf3e90a85ea75 Mon Sep 17 00:00:00 2001
From: Tobrun Van Nuland <tobrun.van.nuland@gmail.com>
Date: Fri, 27 May 2016 08:36:41 +0200
Subject: [PATCH] [android] #5113 - added javadoc to the MarkerView API

---
 .../annotations/BaseMarkerViewOptions.java    | 152 ++++++++++++++-
 .../mapboxsdk/annotations/MarkerView.java     | 182 +++++++++++++++++-
 .../annotations/MarkerViewManager.java        |   2 +-
 .../annotations/MarkerViewOptions.java        |   6 +
 .../com/mapbox/mapboxsdk/maps/MapboxMap.java  |  53 ++++-
 5 files changed, 388 insertions(+), 7 deletions(-)

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java
index 892eee180..0cd54fc0f 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java
@@ -10,9 +10,10 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
  * Abstract builder class for composing custom MarkerView objects.
  * <p>
  * Extending this class requires implementing Parceable interface.
+ * </p>
  *
  * @param <U> Type of the marker view to be composed
- * @param <T> Type of the builder to be used for composing a custom Marker
+ * @param <T> Type of the builder to be used for composing
  */
 public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends BaseMarkerViewOptions<U, T>> implements Parcelable {
 
@@ -30,120 +31,265 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base
     protected int rotation;
     protected boolean visible = true;
 
+    /**
+     * Default constructor
+     */
     public BaseMarkerViewOptions() {
     }
 
+    /**
+     * Set the geographical location of the MarkerView.
+     *
+     * @param position the location to position the MarkerView
+     * @return the object for which the method was called
+     */
     public T position(@NonNull LatLng position) {
         this.position = position;
         return getThis();
     }
 
+    /**
+     * Set the snippet of the MarkerView.
+     *
+     * @param snippet the snippet of the MarkerView
+     * @return the object for which the method was called
+     */
     public T snippet(String snippet) {
         this.snippet = snippet;
         return getThis();
     }
 
+    /**
+     * Set the title of the MarkerView.
+     *
+     * @param title the title of the MarkerView
+     * @return the object for which the method was called
+     */
     public T title(String title) {
         this.title = title;
         return getThis();
     }
 
+    /**
+     * Set the icon of the MarkerView.
+     *
+     * @param icon the icon of the MarkerView
+     * @return the object for which the method was called
+     */
     public T icon(Icon icon) {
         this.icon = icon;
         return getThis();
     }
 
+    /**
+     * Set the flat state of the MarkerView.
+     *
+     * @param flat the flat state of the MarkerView
+     * @return the object for which the method was called
+     */
     public T flat(boolean flat) {
         this.flat = flat;
         return getThis();
     }
 
+    /**
+     * Set the anchor of the MarkerView.
+     *
+     * @param u the u-value
+     * @param v the v-value
+     * @return the object for which the method was called
+     */
     public T anchor(float u, float v) {
         this.anchorU = u;
         this.anchorV = v;
         return getThis();
     }
 
+    /**
+     * Set the InfoWindow anchor of the MarkerView.
+     *
+     * @param u the u-value
+     * @param v the v-values
+     * @return the object for which the method was called
+     */
     public T infoWindowAnchor(float u, float v) {
         this.infoWindowAnchorU = u;
         this.infoWindowAnchorV = v;
         return getThis();
     }
 
+    /**
+     * Set the animator resource to be used when an MarkerView is selected.
+     *
+     * @param selectAnimRes the used animator resource
+     * @return the object for which the method was called
+     */
     public T selectAnimatorResource(@AnimatorRes int selectAnimRes) {
         this.selectAnimRes = selectAnimRes;
         return getThis();
     }
 
+    /**
+     * Set the animator resource to be used when an MarkerView is deselected.
+     *
+     * @param deselectAnimRes the used animator resource
+     * @return the object for which the method was called
+     */
     public T deselectAnimatorResource(@AnimatorRes int deselectAnimRes) {
         this.deselectAnimRes = deselectAnimRes;
         return getThis();
     }
 
+    /**
+     * Set the rotation of the MarkerView.
+     *
+     * @param rotation the rotation value
+     * @return the object for which the method was called
+     */
     public T rotation(int rotation) {
         this.rotation = rotation;
         return getThis();
     }
 
-    public T visible(boolean visible){
+    /**
+     * Set the visibility state of the MarkerView.
+     *
+     * @param visible the visible state
+     * @return the object for which the method was calleds
+     */
+    public T visible(boolean visible) {
         this.visible = visible;
         return getThis();
     }
 
+    /**
+     * Get the geographical location of the MarkerView.
+     *
+     * @return the geographical location
+     */
     public LatLng getPosition() {
         return position;
     }
 
+    /**
+     * Get the snippet of the MarkerView.
+     *
+     * @return the snippet
+     */
     public String getSnippet() {
         return snippet;
     }
 
+    /**
+     * Get the title of the MarkerView.
+     *
+     * @return the title
+     */
     public String getTitle() {
         return title;
     }
 
+    /**
+     * Get the icon of the MarkerView.
+     *
+     * @return the icon
+     */
     public Icon getIcon() {
         return icon;
     }
 
+    /**
+     * Get the flat state of the MarkerView.
+     *
+     * @return the flat state
+     */
     public boolean isFlat() {
         return flat;
     }
 
+    /**
+     * Get the u-value of the MarkerView anchor.
+     *
+     * @return the u-value
+     */
     public float getAnchorU() {
         return anchorU;
     }
 
+    /**
+     * Get the v-value of the MarkerView anchor.
+     *
+     * @return the v-value
+     */
     public float getAnchorV() {
         return anchorV;
     }
 
+    /**
+     * Get the u-value of the MarkerView InfoWindow anchor.
+     *
+     * @return the u-value
+     */
     public float getInfoWindowAnchorU() {
         return infoWindowAnchorU;
     }
 
+    /**
+     * Get the v-value of the MarkerView InfoWindow anchor.
+     *
+     * @return the v-value
+     */
     public float getInfoWindowAnchorV() {
         return infoWindowAnchorV;
     }
 
+    /**
+     * Get the animator resource used for selecting the MarkerView.
+     *
+     * @return the animator resource
+     */
     public int getSelectAnimRes() {
         return selectAnimRes;
     }
 
+    /**
+     * Get the animator resource used for deselecting the MarkerView.
+     *
+     * @return the animator resource
+     */
     public int getDeselectAnimRes() {
         return deselectAnimRes;
     }
 
+    /**
+     * Get the rotation of the MarkerView.
+     *
+     * @return the rotation value
+     */
     public int getRotation() {
         return rotation;
     }
 
+    /**
+     * Get the visibility state of the MarkerView.
+     *
+     * @return the visibility state
+     */
     public boolean isVisible() {
         return visible;
     }
 
+    /**
+     * Get the instance of the object for which this method was called.
+     *
+     * @return the object for which the this method was called
+     */
     public abstract T getThis();
 
+    /**
+     * Get the MarkerView.
+     *
+     * @return the MarkerView created from this builder
+     */
     public abstract U getMarker();
-
 }
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 87209e3f0..3e5104464 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
@@ -2,6 +2,16 @@ package com.mapbox.mapboxsdk.annotations;
 
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 
+/**
+ * MarkerView is an annotation that shows an View at a geographical location.
+ * <p>
+ * 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
+ * </p>
+ */
 public class MarkerView extends Marker {
 
     private MarkerViewManager markerViewManager;
@@ -25,9 +35,17 @@ public class MarkerView extends Marker {
     private float rotation;
     private float alpha = 1;
 
+    /**
+     * Publicly hidden default constructor
+     */
     MarkerView() {
     }
 
+    /**
+     * Creates a instance of MarkerView using the builder of MarkerView
+     *
+     * @param baseMarkerViewOptions the builder used to construct the MarkerView
+     */
     public MarkerView(BaseMarkerViewOptions baseMarkerViewOptions) {
         super(baseMarkerViewOptions);
         this.anchorU = baseMarkerViewOptions.getAnchorU();
@@ -43,80 +61,194 @@ public class MarkerView extends Marker {
         this.anchorV = baseMarkerViewOptions.anchorV;
     }
 
+    /**
+     * Specifies the anchor being set on a particular point 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])
+     */
     public void setAnchor(float u, float v) {
         this.anchorU = u;
         this.anchorV = v;
     }
 
+    /**
+     * Get the horizontal distance, normalized to [0, 1], of the anchor from the left edge.
+     *
+     * @return the u-value of the anchor
+     */
     public float getAnchorU() {
         return anchorU;
     }
 
+    /**
+     * Get the vertical distance, normalized to [0, 1], of the anchor from the top edge.
+     *
+     * @return the v-value of the anchor
+     */
     public float getAnchorV() {
         return anchorV;
     }
 
-    void setOffsetX(float x){
+    /**
+     * Internal method to set the horizontal calculated offset.
+     * <p>
+     * These are calculated based on the View bounds and the provided anchor.
+     * </p>
+     *
+     * @param x the x-value of the offset
+     */
+    void setOffsetX(float x) {
         offsetX = x;
     }
 
-    void setOffsetY(float y){
+    /**
+     * Internal method to set the vertical calculated offset.
+     * <p>
+     * These are calculated based on the View bounds and the provided anchor.
+     * </p>
+     *
+     * @param y the y-value of the offset
+     */
+    void setOffsetY(float y) {
         offsetY = y;
     }
 
+    /**
+     * Internal method to get the horizontal calculated offset
+     *
+     * @return the calculated horizontal offset
+     */
     float getOffsetX() {
         return offsetX;
     }
 
+    /**
+     * Internal method to get the vertical calculated offset
+     *
+     * @return the calculated vertical offset
+     */
     float getOffsetY() {
         return offsetY;
     }
 
+    /**
+     * 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.
+     * </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])
+     * @see #setAnchor(float, float) for more details.
+     */
     public void setInfoWindowAnchor(float u, float v) {
         this.infoWindowAnchorU = u;
         this.infoWindowAnchorV = v;
     }
 
+    /**
+     * Get the horizontal distance, normalized to [0, 1], of the info window anchor from the left edge.
+     *
+     * @return the u value of the InfoWindow anchor.
+     */
     public float getInfoWindowAnchorU() {
         return infoWindowAnchorU;
     }
 
+    /**
+     * Get the vertical distance, normalized to [0, 1], of the info window anchor from the top edge.
+     *
+     * @return the v value of the InfoWindow anchor.
+     */
     public float getInfoWindowAnchorV() {
         return infoWindowAnchorV;
     }
 
+    /**
+     * Get the flat state of a MarkerView.
+     *
+     * @return true is the MarkerView is flat; false is 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.
+     *
+     * @param flat the flat state of the MarkerView
+     */
     public void setFlat(boolean flat) {
         this.flat = flat;
     }
 
+    /**
+     * Get the animator resource used to animate to the selected state of a MarkerView.
+     *
+     * @return the animator resource used
+     */
     public int getSelectAnimRes() {
         return selectAnimRes;
     }
 
+    /**
+     * Set the animator resource used to animate to the deselected state of a MarkerView.
+     *
+     * @param selectAnimRes the animator resource used
+     */
     public void setSelectAnimRes(int selectAnimRes) {
         this.selectAnimRes = selectAnimRes;
     }
 
+    /**
+     * Get the animator resource used to animate to the deslected state of a MarkerView.
+     *
+     * @return the animator resource used
+     */
     public int getDeselectAnimRes() {
         return deselectAnimRes;
     }
 
+    /**
+     * Set the animator resource used to animate to the selected state of a MarkerView.
+     *
+     * @param deselectAnimRes the animator resource used
+     */
     public void setDeselectAnimRes(int deselectAnimRes) {
         this.deselectAnimRes = deselectAnimRes;
     }
 
+    /**
+     * Internal method to get the current tilted value of a MarkerView.
+     *
+     * @return the tilted value
+     */
     float getTilt() {
         return tiltValue;
     }
 
+    /**
+     * Internal method to set the current titled value of a MarkerView.
+     *
+     * @param tiltValue the tilted value to set
+     */
     void setTilt(float tiltValue) {
         this.tiltValue = tiltValue;
     }
 
+    /**
+     * Set the visible state of a MarkerView.
+     *
+     * @param visible true will make the MarkerView visible, false will hide the MarkerViews
+     */
     public void setVisible(boolean visible) {
         this.visible = visible;
         if (markerViewManager != null) {
@@ -124,10 +256,24 @@ public class MarkerView extends Marker {
         }
     }
 
+    /**
+     * Returns the visible state of the MarkerView.
+     *
+     * @return the visible state
+     */
     public boolean isVisible() {
         return visible;
     }
 
+    /**
+     * Set the rotation value of the MarkerView.
+     * <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
+     */
     public void setRotation(float rotation) {
         this.rotation = rotation;
         if (markerViewManager != null) {
@@ -135,14 +281,33 @@ public class MarkerView extends Marker {
         }
     }
 
+    /**
+     * Get the rotation value of the MarkerView.
+     *
+     * @return the rotation value
+     */
     public float getRotation() {
         return rotation;
     }
 
+    /**
+     * Get the alpha value of the MarkerView.
+     *
+     * @return the alpha value
+     */
     public float getAlpha() {
         return alpha;
     }
 
+    /**
+     * Set the alpha value of the MarkerView.
+     * <p>
+     * This will result in animating the alpha of the MarkerView using an alpha animator
+     * from current value to the provided parameter value.
+     * </p>
+     *
+     * @param alpha the alpha value to animate to
+     */
     public void setAlpha(float alpha) {
         this.alpha = alpha;
         if (markerViewManager != null) {
@@ -150,12 +315,25 @@ public class MarkerView extends Marker {
         }
     }
 
+    /**
+     * Set the MapboxMap associated tot the MapView containing the MarkerView.
+     * <p>
+     * This method is used to instantiate the MarkerView and provide an instance of {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter}
+     * </p>
+     *
+     * @param mapboxMap the MapboxMap instances
+     */
     @Override
     public void setMapboxMap(MapboxMap mapboxMap) {
         super.setMapboxMap(mapboxMap);
         markerViewManager = mapboxMap.getMarkerViewManager();
     }
 
+    /**
+     * Get the String representation of a MarkerView.
+     *
+     * @return the String representation
+     */
     @Override
     public String toString() {
         return "MarkerView [position[" + getPosition() + "]]";
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java
index 03d554656..d9fc9e62a 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java
@@ -37,7 +37,7 @@ public class MarkerViewManager {
      * Creates an instance of MarkerViewManager.
      *
      * @param mapboxMap the MapboxMap associated with the MarkerViewManager
-     * @param mapView   the MapView associarted with the MarkerViewManager
+     * @param mapView   the MapView associated with the MarkerViewManager
      */
     public MarkerViewManager(@NonNull MapboxMap mapboxMap, @NonNull MapView mapView) {
         this.mapboxMap = mapboxMap;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java
index a688a8b1a..0c9faed35 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java
@@ -6,6 +6,12 @@ import android.os.Parcelable;
 
 import com.mapbox.mapboxsdk.geometry.LatLng;
 
+/**
+ * builder class for composing MarkerView objects.
+ * <p>
+ * Do not extend this class directly but extend BaseMarkerViewOptions instead.
+ * </p>
+ */
 public class MarkerViewOptions extends BaseMarkerViewOptions<MarkerView, MarkerViewOptions> {
 
     private MarkerView marker;
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 62cb74979..fbe6a31f6 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
@@ -1214,6 +1214,11 @@ public class MapboxMap {
         return marker;
     }
 
+    /**
+     * Get the MarkerViewManager associated to the MapView.
+     *
+     * @return the associated MarkerViewManager
+     */
     public MarkerViewManager getMarkerViewManager() {
         return mMarkerViewManager;
     }
@@ -1801,12 +1806,22 @@ public class MapboxMap {
         View getInfoWindow(@NonNull Marker marker);
     }
 
+    /**
+     * Interface definition for a callback to be invoked when an MarkerView will be shown.
+     *
+     * @param <U> the instance type of MarkerView
+     */
     public static abstract class MarkerViewAdapter<U extends MarkerView> {
 
         private Context context;
         private final Class<U> persistentClass;
         private final Pools.SimplePool<View> mViewReusePool;
 
+        /**
+         * Create an instance of MarkerViewAdapter.
+         *
+         * @param context the context associated to a MapView
+         */
         @SuppressWarnings("unchecked")
         public MarkerViewAdapter(Context context) {
             this.context = context;
@@ -1814,24 +1829,60 @@ public class MapboxMap {
             mViewReusePool = new Pools.SimplePool<>(20);
         }
 
+        /**
+         * Called when an MarkerView will be added to the MapView.
+         *
+         * @param marker      the model representing the MarkerView
+         * @param convertView the reusable view
+         * @param parent      the parent ViewGroup of the convertview
+         * @return the View that is adapted to the contents of MarkerView
+         */
         @Nullable
         public abstract View getView(@NonNull U marker, @NonNull View convertView, @NonNull ViewGroup parent);
 
+        /**
+         * Returns the generic type of the used MarkerView.
+         *
+         * @return the generic type
+         */
         public Class<U> getMarkerClass() {
             return persistentClass;
         }
 
+        /**
+         * Returns the pool used to store reusable Views.
+         *
+         * @return the pool associated to this adapter
+         */
         public Pools.SimplePool<View> getViewReusePool() {
             return mViewReusePool;
         }
 
+        /**
+         * Returns the context associated to the hosting MapView.
+         *
+         * @return the context used
+         */
         public Context getContext() {
             return context;
         }
     }
 
+    /**
+     * Interface definition for a callback to be invoked when the user clicks on a MarkerView.
+     *
+     * @see MarkerViewManager#setOnMarkerViewClickListener(OnMarkerViewClickListener)
+     */
     public interface OnMarkerViewClickListener {
 
+        /**
+         * Called when the user clicks on a MarkerView.
+         *
+         * @param marker  the MarkerView associated to the clicked View
+         * @param view    the clicked View
+         * @param adapter the adapter used to adapt the MarkerView to the View
+         * @return If true the listener has consumed the event and the info window will not be shown
+         */
         boolean onMarkerClick(@NonNull Marker marker, @NonNull View view, @NonNull MarkerViewAdapter adapter);
     }
 
@@ -1903,7 +1954,7 @@ public class MapboxMap {
     public interface SnapshotReadyCallback {
         /**
          * Invoked when the snapshot has been taken.
-         **/
+         */
         void onSnapshotReady(Bitmap snapshot);
     }