[android][wip] minimal camera docs

4 files changed, 89 insertions, 10 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/CameraTransition.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/CameraTransition.java
index 6ec240d115..35c8ca803f 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/CameraTransition.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/CameraTransition.java
@@ -5,6 +5,7 @@ import android.view.animation.Interpolator;
 
 import com.mapbox.mapboxsdk.constants.MapboxConstants;
 
+import java.util.List;
 import java.util.concurrent.CopyOnWriteArrayList;
 
 public abstract class CameraTransition<T> {
@@ -17,14 +18,14 @@ public abstract class CameraTransition<T> {
   public static final Interpolator INTERPOLATOR_LINEAR = PathInterpolatorCompat.create(0f, 0f, 1f, 1f);
   public static final Interpolator INTERPOLATOR_EASING = PathInterpolatorCompat.create(0f, 0f, 0.25f, 1f);
 
-  public static final int PROPERTY_CENTER = 0;
+  public static final int PROPERTY_TARGET = 0;
   public static final int PROPERTY_ZOOM = 1;
   public static final int PROPERTY_PITCH = 2;
   public static final int PROPERTY_BEARING = 3;
   public static final int PROPERTY_ANCHOR = 4;
   public static final int PROPERTY_PADDING = 5;
 
-  private final CopyOnWriteArrayList<Listener> listeners = new CopyOnWriteArrayList<>();
+  private final List<Listener> listeners = new CopyOnWriteArrayList<>();
 
   private final int reason;
 
@@ -152,10 +153,16 @@ public abstract class CameraTransition<T> {
     return interpolator;
   }
 
+  /**
+   * Add a listener that gets notified about states of the transition.
+   */
   public void addListener(Listener listener) {
     listeners.add(listener);
   }
 
+  /**
+   * Remove a listener that gets notified about states of the transition.
+   */
   public void removeListener(Listener listener) {
     listeners.remove(listener);
   }
@@ -205,6 +212,9 @@ public abstract class CameraTransition<T> {
 
   protected abstract T getAnimatedValue(double fraction);
 
+  /**
+   * Listener that notifies about different states of the transition.
+   */
   public interface Listener {
 
     void onProgress(CameraTransition transition);
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapCameraController.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapCameraController.java
index 33860f3735..1d6751f0fd 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapCameraController.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapCameraController.java
@@ -34,7 +34,7 @@ public class MapCameraController {
 
   MapCameraController(@NonNull final Transform transform) {
     this.transform = transform;
-    queuedTransitions.put(CameraTransition.PROPERTY_CENTER, new LinkedList<CameraTransition>());
+    queuedTransitions.put(CameraTransition.PROPERTY_TARGET, new LinkedList<CameraTransition>());
     queuedTransitions.put(CameraTransition.PROPERTY_ZOOM, new LinkedList<CameraTransition>());
     queuedTransitions.put(CameraTransition.PROPERTY_PITCH, new LinkedList<CameraTransition>());
     queuedTransitions.put(CameraTransition.PROPERTY_BEARING, new LinkedList<CameraTransition>());
@@ -103,8 +103,12 @@ public class MapCameraController {
     }
   };
 
+  /**
+   * Starts transition immediately. Transition's delay doesn't queue the transition,
+   * but blocks the slot until the delay time is fulfilled.
+   */
   public void startTransition(CameraTransition transition) {
-    behavior.animationScheduled(this, transition);
+    behavior.animationStarted(this, transition);
 
     final CameraTransition runningTransition = runningTransitions.get(transition.getCameraProperty());
     if (runningTransition != null) {
@@ -124,6 +128,11 @@ public class MapCameraController {
     }
   }
 
+  /**
+   * Queues the transition. The transition is going to be executed immediately if there are other transitions
+   * changing the same property as the scheduled one. If there is a running animation,
+   * the queued one is going to get started when the running one finished or gets canceled.
+   */
   public void queueTransition(CameraTransition transition) {
     CameraTransition running = runningTransitions.get(transition.getCameraProperty());
     LinkedList<CameraTransition> queued = queuedTransitions.get(transition.getCameraProperty());
@@ -135,6 +144,9 @@ public class MapCameraController {
     }
   }
 
+  /**
+   * Cancels queued transitions.
+   */
   public void cancelQueuedTransitions() {
     List<CameraTransition> canceled = new ArrayList<>();
     for (List<CameraTransition> transitions : queuedTransitions.values()) {
@@ -151,6 +163,9 @@ public class MapCameraController {
     }
   }
 
+  /**
+   * Cancels running transitions.
+   */
   public void cancelRunningTransitions() {
     List<CameraTransition> canceled = new ArrayList<>();
     Iterator<CameraTransition> iterator = runningTransitions.values().iterator();
@@ -166,38 +181,70 @@ public class MapCameraController {
     }
   }
 
+  /**
+   * Cancels all transitions.
+   */
   public void cancelAllTransitions() {
     cancelQueuedTransitions();
     cancelRunningTransitions();
   }
 
+  /**
+   * Adds a camera listener.
+   */
   public void addOnCameraChangedListener(OnCameraChangedListener listener) {
     cameraChangedListeners.add(listener);
   }
 
+  /**
+   * Removes a camera listener.
+   */
   public void removeOnCameraChangedListener(OnCameraChangedListener listener) {
     cameraChangedListeners.remove(listener);
   }
 
+  /**
+   * Returns all queued transitions. The returned objects maps the camera property,
+   * for example {@link CameraTransition#PROPERTY_TARGET} or {@link CameraTransition#PROPERTY_ZOOM},
+   * to the list of queued transitions that will animate this property.
+   */
   @NonNull
   public HashMap<Integer, LinkedList<CameraTransition>> getQueuedTransitions() {
     return new HashMap<>(queuedTransitions);
   }
 
+  /**
+   * Returns all running transitions. The returned objects maps the camera property,
+   * for example {@link CameraTransition#PROPERTY_TARGET} or {@link CameraTransition#PROPERTY_ZOOM},
+   * to the currently running transition.
+   */
   @NonNull
   public HashMap<Integer, CameraTransition> getRunningTransitions() {
     return new HashMap<>(runningTransitions);
   }
 
+  /**
+   * Returns the currently set behavior.
+   */
   @NonNull
   public CameraBehavior getBehavior() {
     return behavior;
   }
 
+  /**
+   * Sets the behavior.
+   */
   public void setBehavior(@NonNull CameraBehavior behavior) {
     this.behavior = behavior;
   }
 
+  /**
+   * Returns the current camera position.
+   */
+  public CameraPosition getCameraPosition() {
+    return transform.getCameraPosition();
+  }
+
   void onDestroy() {
     cancelAllTransitions();
     choreographer.removeFrameCallback(frameCallback);
@@ -205,7 +252,7 @@ public class MapCameraController {
 
   private static void setCameraProperty(CameraPosition.Builder builder, int property, Object value) {
     switch (property) {
-      case CameraTransition.PROPERTY_CENTER:
+      case CameraTransition.PROPERTY_TARGET:
         builder.target(value == null ? null : (LatLng) value);
         break;
 
@@ -239,7 +286,7 @@ public class MapCameraController {
     CameraPosition cameraPosition = transform.getCameraPosition();
     assert cameraPosition != null;
     switch (property) {
-      case CameraTransition.PROPERTY_CENTER:
+      case CameraTransition.PROPERTY_TARGET:
         return cameraPosition.target;
 
       case CameraTransition.PROPERTY_ZOOM:
@@ -274,10 +321,26 @@ public class MapCameraController {
     }
   }
 
+  /**
+   * Camera behavior's methods are called in various state of the camera transition.
+   * It can be used to achieve a desired outcome when transitions collide (try to change the same camera property)
+   * or perform business logic that would otherwise have to be handled in many other places that schedule animations.
+   */
   public interface CameraBehavior {
 
-    void animationScheduled(MapCameraController controller, CameraTransition transition);
-
+    /**
+     * Called whenever a transition is started. If a transition is queued,
+     * it's only going to be started when at the top of the queue.
+     */
+    void animationStarted(MapCameraController controller, CameraTransition transition);
+
+    /**
+     * Called whenever there's a transition scheduled to be started,
+     * but another one is already changing the requested camera property.
+     * <p>
+     * The transition that is going be returned by this method is going to be executed (or allowed to finish),
+     * the other one is going to get canceled immediately.
+     */
     @NonNull
     CameraTransition resolve(CameraTransition currentTransition, CameraTransition interruptingTransition);
   }
@@ -286,10 +349,13 @@ public class MapCameraController {
     void onCameraChanged();
   }
 
+  /**
+   * Default implementation of the camera behavior.
+   */
   public static class DefaultCameraBehavior implements CameraBehavior {
 
     @Override
-    public void animationScheduled(MapCameraController controller, CameraTransition transition) {
+    public void animationStarted(MapCameraController controller, CameraTransition transition) {
       if (transition.getReason() == CameraTransition.REASON_GESTURE) {
         for (CameraTransition currentTransition : controller.getRunningTransitions().values()) {
           if (currentTransition.getReason() != CameraTransition.REASON_GESTURE) {
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 1aec486fbc..23319aaef9 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
@@ -2392,6 +2392,9 @@ public final class MapboxMap {
     }
   }
 
+  /**
+   * Returns the camera controller that manages camera transitions.
+   */
   public MapCameraController getCameraController() {
     return cameraController;
   }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TargetCameraTransition.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TargetCameraTransition.java
index effed30984..387344c26d 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TargetCameraTransition.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TargetCameraTransition.java
@@ -14,7 +14,7 @@ public class TargetCameraTransition extends CameraTransition<LatLng> {
 
   @Override
   int getCameraProperty() {
-    return PROPERTY_CENTER;
+    return PROPERTY_TARGET;
   }
 
   @Override