[viewport] Refinements to public API documentation.

plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/ViewportExt.kt

@@ -8,6 +8,11 @@ import com.mapbox.maps.plugin.delegates.MapPluginProviderDelegate
 
 /**
  * Extension val for MapView to get the [ViewportPlugin] instance.
+ *
+ * [ViewportPlugin] is a high-level and extensible API for driving the map camera. It
+ * provides built-in states for following the location puck and showing an overview of
+ * a GeoJSON geometry. Transitions between states can be animated with a built-in
+ * default transition and via custom transitions.
  */
 @MapboxExperimental
 val MapPluginProviderDelegate.viewport: ViewportPlugin

plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/transition/ImmediateViewportTransition.kt

@@ -6,11 +6,14 @@ import com.mapbox.maps.plugin.animation.MapAnimationOptions.Companion.mapAnimati
 import com.mapbox.maps.plugin.animation.camera
 import com.mapbox.maps.plugin.delegates.MapDelegateProvider
 import com.mapbox.maps.plugin.viewport.CompletionListener
+import com.mapbox.maps.plugin.viewport.ViewportPlugin
 import com.mapbox.maps.plugin.viewport.ViewportPluginImpl.Companion.VIEWPORT_CAMERA_OWNER
 import com.mapbox.maps.plugin.viewport.state.ViewportState
 
 /**
- * [ViewportTransition] that transition to target [ViewportState] immediately.
+ * The [ViewportTransition] that transition to target [ViewportState] immediately without any animation.
+ *
+ * Use [ViewportPlugin.makeImmediateViewportTransition] to create instances of ImmediateViewportTransition.
  */
 internal class ImmediateViewportTransition(delegateProvider: MapDelegateProvider) :
   ViewportTransition {

sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/CompletionListener.kt

@@ -10,8 +10,11 @@ fun interface CompletionListener {
   /**
    * Notifies the action is completed.
    *
+   * Transition may end early if they fail or are interrupted(e.g. by another call to [ViewportPlugin.transitionTo]
+   * or [ViewportPlugin.idle]).
+   *
    * @param isFinished true if the transition ran to completion and false
-   * if it was canceled.
+   * if it was canceled or interrupted.
    */
   fun onComplete(isFinished: Boolean)
 }

sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportPlugin.kt

@@ -13,69 +13,99 @@ import com.mapbox.maps.plugin.viewport.transition.DefaultViewportTransition
 import com.mapbox.maps.plugin.viewport.transition.ViewportTransition
 
 /**
- * The Viewport plugin allows to track objects on a map.
+ * The [ViewportPlugin] provides a structured approach to organizing camera management logic into states
+ * and transitions between them.
  *
- * It provides a structured approach to organizing camera management logic into states and transitions between them.
- *
- * at any given time, the viewport is either:
+ * At any given time, the viewport is either:
  *  - idle (not updating the camera)
- *  - in a state (camera is being managed by a ViewportState)
- *  - transitioning (camera is being managed by a ViewportTransition)
+ *  - in a state (camera is being managed by a [ViewportState])
+ *  - transitioning (camera is being managed by a [ViewportTransition])
  */
 @MapboxExperimental
 interface ViewportPlugin : MapPlugin {
 
   /**
    * Returns current [ViewportStatus].
    *
+   * [ViewportStatus] can not be set directly, use [ViewportPlugin.transitionTo] and [ViewportPlugin.idle]
+   * to transition to a state or to idle.
+   *
+   * Defaults to [ViewportStatus.Idle]
+   *
    * @see addStatusObserver
+   * @see removeStatusObserver
    */
   val status: ViewportStatus
 
   /**
    * Executes a transition to requested state.
    *
-   * When started, goes to [ViewportTransition]
-   * and to the final [ViewportState] when ended.
+   * When called, the [status] goes to [ViewportTransition] and to the final [ViewportState] when ended.
+   *
+   * Transitioning to state 'x' when the current [status] is 'ViewportStatus.State(x)' invokes [completionListener]
+   * synchronously with true and does not modify [ViewportPlugin.status].
    *
-   * If transition is canceled, state goes to IDLE.
+   * Transitioning to state 'x' when the current [status] is 'ViewportStatus.Transition(_, x)' invokes
+   * [completionListener] synchronously with false and does not modify [ViewportPlugin.status].
+   *
+   * If transition is failed or canceled, [status] goes to [ViewportStatus.Idle].
    *
    * @param targetState The target [ViewportState] to transition to.
-   * @param transition The [ViewportTransition] that's used to transition to target state, if not specified, the [ViewportPlugin.defaultTransition] will be used.
-   * @param completionListener The listener to observe the completion state.
+   * @param transition The [ViewportTransition] that's used to transition to target state, if not specified, the [ViewportPlugin.defaultTransition] will be used. Defaults to null.
+   * @param completionListener The listener that's invoked when the transition ends, defaults to null.
    */
   fun transitionTo(targetState: ViewportState, transition: ViewportTransition? = null, completionListener: CompletionListener? = null)
 
   /**
-   * Immediately goes to IDLE state canceling all ongoing transitions.
+   * Sets [ViewportPlugin.status] to [ViewportStatus.Idle] synchronously.
+   *
+   * This cancels any active [ViewportState] or [ViewportTransition].
    */
   fun idle()
 
   /**
-   * Options that impact the [ViewportPlugin].
+   * Configuration options that impact the [ViewportPlugin].
    */
   var options: ViewportOptions
 
   // Transitions
 
   /**
-   * DefaultViewportTransition with default options.
+   * [ViewportPlugin.transitionTo] uses this transition unless some non-null value is passed to its
+   * transition argument.
    *
-   * This transition is used unless overridden by one of the registered transitions.
+   * Defaults to [DefaultViewportTransition] with default options.
    */
   var defaultTransition: ViewportTransition
 
   // Observers
 
   /**
-   * Adds [ViewportStatusObserver] to observe the status change.
+   * Subscribes [ViewportStatusObserver] to observe the [ViewportStatus] change.
+   *
+   * [ViewportPlugin] keeps a strong reference to registered observers. Adding the same observer again
+   * while it is already subscribed has no effect.
+   *
+   * Note: Observers are notified of status changes asynchronously on the main queue. This means that
+   * by the time the notification is delivered, the status may have already changed again. This behaviour
+   * is necessary to allow observers to trigger further transitions while avoiding out-of-order delivery
+   * of status changed notifications.
+   *
+   * @param viewportStatusObserver the observer that will be notified when the [ViewportPlugin.status] changes.
+   * @see removeStatusObserver
    */
   fun addStatusObserver(
     viewportStatusObserver: ViewportStatusObserver
   )
 
   /**
-   * Removes [ViewportStatusObserver].
+   * Unsubscribes [ViewportStatusObserver] from [ViewportPlugin.status] changes.
+   *
+   * This causes [ViewportPlugin] to release its strong reference to the observer. Removing an observer
+   * that is not subscribed has no effect.
+   *
+   * @param viewportStatusObserver the observer that should no longer be notified when the [ViewportPlugin.status] changes.
+   * @see addStatusObserver
    */
   fun removeStatusObserver(
     viewportStatusObserver: ViewportStatusObserver
@@ -84,32 +114,37 @@ interface ViewportPlugin : MapPlugin {
   // Convenient methods to create the in-stock [ViewportState] and [ViewportTransition].
 
   /**
-   * Create a [FollowPuckViewportState] instance with provided [FollowPuckViewportStateOptions].
+   * Create a new [FollowPuckViewportState] instance with provided [FollowPuckViewportStateOptions].
    *
-   * @param options The desired [FollowPuckViewportStateOptions]
+   * @param options The desired [FollowPuckViewportStateOptions], defaults to [FollowPuckViewportStateOptions] that's initialised with default parameters.
+   * @return The newly-created [FollowPuckViewportState] instance.
    */
   fun makeFollowPuckViewportState(
     options: FollowPuckViewportStateOptions = FollowPuckViewportStateOptions.Builder().build()
   ): FollowPuckViewportState
 
   /**
-   * Create an [OverviewViewportState] instance with provided [OverviewViewportStateOptions].
+   * Create a new [OverviewViewportState] instance with provided [OverviewViewportStateOptions].
    *
    * @param options The desired [OverviewViewportStateOptions]
+   * @return The newly-created [OverviewViewportState] instance.
    */
   fun makeOverviewViewportState(options: OverviewViewportStateOptions): OverviewViewportState
 
   /**
-   * Create a default [ViewportTransition] instance with provided [DefaultViewportTransitionOptions].
+   * Create a new [DefaultViewportTransition] instance with provided [DefaultViewportTransitionOptions].
    *
-   * @param options The desired [DefaultViewportTransitionOptions]
+   * @param options The desired [DefaultViewportTransitionOptions], defaults to [DefaultViewportTransitionOptions] that's initialised with default parameters.
+   * @return The newly-created [DefaultViewportTransition] instance.
    */
   fun makeDefaultViewportTransition(
     options: DefaultViewportTransitionOptions = DefaultViewportTransitionOptions.Builder().build()
   ): DefaultViewportTransition
 
   /**
-   * Create a [ViewportTransition] instance that transition to the target [ViewportState] immediately.
+   * Create a new [ViewportTransition] instance that transition to the target [ViewportState] immediately.
+   *
+   * @return The newly-created ImmediateViewportTransition instance.
    */
   fun makeImmediateViewportTransition(): ViewportTransition
 }

sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatus.kt

@@ -8,7 +8,10 @@ import java.util.*
 /**
  * Represents the status of the viewport.
  *
- * It could be either a [ViewportState] or [ViewportTransition].
+ * It could be either a [ViewportStatus.State], [ViewportStatus.Transition] or [ViewportStatus.Idle].
+ *
+ * The [ViewportStatus.State] amd [ViewportStatus.Transition] have associated values that are reference
+ * types, so equality and hash are implemented in terms of the identities of those objects.
  */
 @MapboxExperimental
 sealed class ViewportStatus {

sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatusObserver.kt

@@ -5,6 +5,9 @@ import com.mapbox.maps.plugin.viewport.data.ViewportStatusChangeReason
 
 /**
  * Observer that gets notified whenever [ViewportStatus] changes.
+ *
+ * @see [ViewportPlugin.addStatusObserver]
+ * @see [ViewportPlugin.removeStatusObserver]
  */
 @MapboxExperimental
 fun interface ViewportStatusObserver {

sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/DefaultViewportTransitionOptions.kt

@@ -2,15 +2,15 @@ package com.mapbox.maps.plugin.viewport.data
 
 import com.mapbox.maps.MapboxExperimental
 import com.mapbox.maps.plugin.viewport.DEFAULT_TRANSITION_MAX_DURATION_MS
+import com.mapbox.maps.plugin.viewport.transition.DefaultViewportTransition
 
 /**
- * Options that impact the [DefaultViewportTransition].
+ * Configuration options that impact the [DefaultViewportTransition].
  */
 @MapboxExperimental
 class DefaultViewportTransitionOptions private constructor(
   /**
-   * The maximum duration of the transitions in milliseconds,
-   * including delays between animators and their respective durations.
+   * The maximum duration of the transitions in milliseconds.
    *
    * Defaults to [DEFAULT_TRANSITION_MAX_DURATION_MS] milliseconds.
    */
@@ -45,8 +45,7 @@ class DefaultViewportTransitionOptions private constructor(
     private var maxDurationMs: Long = DEFAULT_TRANSITION_MAX_DURATION_MS
 
     /**
-     * Sets maximum duration of the generated transitions set in milliseconds,
-     * including delays between animators and their respective durations.
+     * Sets maximum duration of the generated transitions set in milliseconds.
      *
      * Defaults to [DEFAULT_TRANSITION_MAX_DURATION_MS] milliseconds.
      */

sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateBearing.kt

@@ -1,15 +1,18 @@
 package com.mapbox.maps.plugin.viewport.data
 
+import com.mapbox.maps.CameraOptions
 import com.mapbox.maps.MapboxExperimental
+import com.mapbox.maps.plugin.viewport.state.FollowPuckViewportState
 import java.util.Objects
 
 /**
- * Describes the camera bearing options for the [FollowPuckViewportState].
+ * Describes different ways that [FollowPuckViewportState] can obtain values to use when setting
+ * [CameraOptions.bearing].
  */
 @MapboxExperimental
 sealed class FollowPuckViewportStateBearing {
   /**
-   * The viewport's bearing is fixed to the given bearing.
+   * The [FollowPuckViewportState] sets the camera bearing to the constant value on every frame.
    *
    * @param bearing The bearing that the [FollowPuckViewportState] uses to generate camera updates.
    */
@@ -31,10 +34,10 @@ sealed class FollowPuckViewportStateBearing {
   }
 
   /**
-   * The viewport's bearing is set as the same as the location puck's bearing.
+   * The [FollowPuckViewportState] sets the camera bearing to the same as the location puck's bearing.
    *
    * When set to this mode, the viewport's bearing is driven by the location, thus guarantees
-   * synchronization.
+   * the synchronization of the location puck and camera position.
    */
   object SyncWithLocationPuck : FollowPuckViewportStateBearing() {
     /**