Cleanup Video API javadoc.

- Cleaned up documentation and added more details where possible.
- Also added cross references from the VideoProvider and VideoCall
APIs to make it more clear what the link is between the two.

Bug: 21520606
Change-Id: I0a79450d69841df5850061311a523b37688efc49

2 files changed, 313 insertions, 118 deletions

diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java
index f9e48b6..e2bbc62 100644
--- a/telecomm/java/android/telecom/Connection.java
+++ b/telecomm/java/android/telecom/Connection.java
@@ -22,6 +22,7 @@ import com.android.internal.telecom.IVideoProvider;
 
 import android.annotation.Nullable;
 import android.annotation.SystemApi;
+import android.hardware.camera2.CameraManager;
 import android.net.Uri;
 import android.os.Bundle;
 import android.os.Handler;
@@ -339,65 +340,92 @@ public abstract class Connection extends Conferenceable {
         public void onExtrasChanged(Connection c, Bundle extras) {}
     }
 
+    /**
+     * Provides a means of controlling the video session associated with a {@link Connection}.
+     * <p>
+     * Implementations create a custom subclass of {@link VideoProvider} and the
+     * {@link ConnectionService} creates an instance sets it on the {@link Connection} using
+     * {@link Connection#setVideoProvider(VideoProvider)}.  Any connection which supports video
+     * should set the {@link VideoProvider}.
+     * <p>
+     * The {@link VideoProvider} serves two primary purposes: it provides a means for Telecom and
+     * {@link InCallService} implementations to issue requests related to the video session;
+     * it provides a means for the {@link ConnectionService} to report events and information
+     * related to the video session to Telecom and the {@link InCallService} implementations.
+     * <p>
+     * {@link InCallService} implementations interact with the {@link VideoProvider} via
+     * {@link android.telecom.InCallService.VideoCall}.
+     */
     public static abstract class VideoProvider {
 
         /**
          * Video is not being received (no protocol pause was issued).
+         * @see #handleCallSessionEvent(int)
          */
         public static final int SESSION_EVENT_RX_PAUSE = 1;
 
         /**
-         * Video reception has resumed after a SESSION_EVENT_RX_PAUSE.
+         * Video reception has resumed after a {@link #SESSION_EVENT_RX_PAUSE}.
+         * @see #handleCallSessionEvent(int)
          */
         public static final int SESSION_EVENT_RX_RESUME = 2;
 
         /**
          * Video transmission has begun. This occurs after a negotiated start of video transmission
          * when the underlying protocol has actually begun transmitting video to the remote party.
+         * @see #handleCallSessionEvent(int)
          */
         public static final int SESSION_EVENT_TX_START = 3;
 
         /**
          * Video transmission has stopped. This occurs after a negotiated stop of video transmission
          * when the underlying protocol has actually stopped transmitting video to the remote party.
+         * @see #handleCallSessionEvent(int)
          */
         public static final int SESSION_EVENT_TX_STOP = 4;
 
         /**
-         * A camera failure has occurred for the selected camera.  The In-Call UI can use this as a
-         * cue to inform the user the camera is not available.
+         * A camera failure has occurred for the selected camera.  The {@link InCallService} can use
+         * this as a cue to inform the user the camera is not available.
+         * @see #handleCallSessionEvent(int)
          */
         public static final int SESSION_EVENT_CAMERA_FAILURE = 5;
 
         /**
-         * Issued after {@code SESSION_EVENT_CAMERA_FAILURE} when the camera is once again ready for
-         * operation.  The In-Call UI can use this as a cue to inform the user that the camera has
-         * become available again.
+         * Issued after {@link #SESSION_EVENT_CAMERA_FAILURE} when the camera is once again ready
+         * for operation.  The {@link InCallService} can use this as a cue to inform the user that
+         * the camera has become available again.
+         * @see #handleCallSessionEvent(int)
          */
         public static final int SESSION_EVENT_CAMERA_READY = 6;
 
         /**
          * Session modify request was successful.
+         * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
          */
         public static final int SESSION_MODIFY_REQUEST_SUCCESS = 1;
 
         /**
          * Session modify request failed.
+         * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
          */
         public static final int SESSION_MODIFY_REQUEST_FAIL = 2;
 
         /**
          * Session modify request ignored due to invalid parameters.
+         * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
          */
         public static final int SESSION_MODIFY_REQUEST_INVALID = 3;
 
         /**
          * Session modify request timed out.
+         * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
          */
         public static final int SESSION_MODIFY_REQUEST_TIMED_OUT = 4;
 
         /**
-         * Session modify request rejected by remote UE.
+         * Session modify request rejected by remote user.
+         * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
          */
         public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE = 5;
 
@@ -569,9 +597,17 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Sets the camera to be used for video recording in a video connection.
+         * Sets the camera to be used for the outgoing video.
+         * <p>
+         * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
+         * camera via
+         * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#setCamera(String)}.
          *
-         * @param cameraId The id of the camera.
+         * @param cameraId The id of the camera (use ids as reported by
+         * {@link CameraManager#getCameraIdList()}).
          */
         public abstract void onSetCamera(String cameraId);
 
@@ -579,21 +615,30 @@ public abstract class Connection extends Conferenceable {
          * Sets the surface to be used for displaying a preview of what the user's camera is
          * currently capturing.  When video transmission is enabled, this is the video signal which
          * is sent to the remote device.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#setPreviewSurface(Surface)}.
          *
-         * @param surface The surface.
+         * @param surface The {@link Surface}.
          */
         public abstract void onSetPreviewSurface(Surface surface);
 
         /**
          * Sets the surface to be used for displaying the video received from the remote device.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#setDisplaySurface(Surface)}.
          *
-         * @param surface The surface.
+         * @param surface The {@link Surface}.
          */
         public abstract void onSetDisplaySurface(Surface surface);
 
         /**
          * Sets the device orientation, in degrees.  Assumes that a standard portrait orientation of
          * the device is 0 degrees.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#setDeviceOrientation(int)}.
          *
          * @param rotation The device orientation, in degrees.
          */
@@ -601,57 +646,100 @@ public abstract class Connection extends Conferenceable {
 
         /**
          * Sets camera zoom ratio.
+         * <p>
+         * Sent from the {@link InCallService} via {@link InCallService.VideoCall#setZoom(float)}.
          *
          * @param value The camera zoom ratio.
          */
         public abstract void onSetZoom(float value);
 
         /**
-         * Issues a request to modify the properties of the current session.  The request is
-         * sent to the remote device where it it handled by the In-Call UI.
-         * Some examples of session modification requests: upgrade connection from audio to video,
-         * downgrade connection from video to audio, pause video.
+         * Issues a request to modify the properties of the current video session.
+         * <p>
+         * Example scenarios include: requesting an audio-only call to be upgraded to a
+         * bi-directional video call, turning on or off the user's camera, sending a pause signal
+         * when the {@link InCallService} is no longer the foreground application.
+         * <p>
+         * If the {@link VideoProvider} determines a request to be invalid, it should call
+         * {@link #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)} to report the
+         * invalid request back to the {@link InCallService}.
+         * <p>
+         * Where a request requires confirmation from the user of the peer device, the
+         * {@link VideoProvider} must communicate the request to the peer device and handle the
+         * user's response.  {@link #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)}
+         * is used to inform the {@link InCallService} of the result of the request.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#sendSessionModifyRequest(VideoProfile)}.
          *
-         * @param fromProfile The video properties prior to the request.
-         * @param toProfile The video properties with the requested changes made.
+         * @param fromProfile The video profile prior to the request.
+         * @param toProfile The video profile with the requested changes made.
          */
         public abstract void onSendSessionModifyRequest(VideoProfile fromProfile,
                 VideoProfile toProfile);
 
-        /**te
-         * Provides a response to a request to change the current connection session video
-         * properties.
-         * This is in response to a request the InCall UI has received via the InCall UI.
+        /**
+         * Provides a response to a request to change the current video session properties.
+         * <p>
+         * For example, if the peer requests and upgrade from an audio-only call to a bi-directional
+         * video call, could decline the request and keep the call as audio-only.
+         * In such a scenario, the {@code responseProfile} would have a video state of
+         * {@link VideoProfile#STATE_AUDIO_ONLY}.  If the user had decided to accept the request,
+         * the video state would be {@link VideoProfile#STATE_BIDIRECTIONAL}.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#sendSessionModifyResponse(VideoProfile)} in response to
+         * a {@link InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile)}
+         * callback.
          *
-         * @param responseProfile The response connection video properties.
+         * @param responseProfile The response video profile.
          */
         public abstract void onSendSessionModifyResponse(VideoProfile responseProfile);
 
         /**
-         * Issues a request to the video provider to retrieve the camera capabilities.
-         * Camera capabilities are reported back to the caller via the In-Call UI.
+         * Issues a request to the {@link VideoProvider} to retrieve the camera capabilities.
+         * <p>
+         * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
+         * camera via
+         * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#requestCameraCapabilities()}.
          */
         public abstract void onRequestCameraCapabilities();
 
         /**
-         * Issues a request to the video telephony framework to retrieve the cumulative data usage
-         * for the current connection.  Data usage is reported back to the caller via the
-         * InCall UI.
+         * Issues a request to the {@link VideoProvider} to retrieve the current data usage for the
+         * video component of the current {@link Connection}.
+         * <p>
+         * The {@link VideoProvider} should respond by communicating current data usage, in bytes,
+         * via {@link VideoProvider#setCallDataUsage(long)}.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#requestCallDataUsage()}.
          */
         public abstract void onRequestConnectionDataUsage();
 
         /**
-         * Provides the video telephony framework with the URI of an image to be displayed to remote
-         * devices when the video signal is paused.
+         * Provides the {@link VideoProvider} with the {@link Uri} of an image to be displayed to
+         * the peer device when the video signal is paused.
+         * <p>
+         * Sent from the {@link InCallService} via
+         * {@link InCallService.VideoCall#setPauseImage(Uri)}.
          *
          * @param uri URI of image to display.
          */
         public abstract void onSetPauseImage(Uri uri);
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
+         * Used to inform listening {@link InCallService} implementations when the
+         * {@link VideoProvider} receives a session modification request.
+         * <p>
+         * Received by the {@link InCallService} via
+         * {@link InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile)},
          *
-         * @param videoProfile The requested video connection profile.
+         * @param videoProfile The requested video profile.
+         * @see #onSendSessionModifyRequest(VideoProfile, VideoProfile)
          */
         public void receiveSessionModifyRequest(VideoProfile videoProfile) {
             if (mVideoCallbacks != null) {
@@ -665,14 +753,22 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
+         * Used to inform listening {@link InCallService} implementations when the
+         * {@link VideoProvider} receives a response to a session modification request.
+         * <p>
+         * Received by the {@link InCallService} via
+         * {@link InCallService.VideoCall.Callback#onSessionModifyResponseReceived(int,
+         * VideoProfile, VideoProfile)}.
          *
          * @param status Status of the session modify request.  Valid values are
          *               {@link VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS},
          *               {@link VideoProvider#SESSION_MODIFY_REQUEST_FAIL},
-         *               {@link VideoProvider#SESSION_MODIFY_REQUEST_INVALID}
-         * @param requestedProfile The original request which was sent to the remote device.
-         * @param responseProfile The actual profile changes made by the remote device.
+         *               {@link VideoProvider#SESSION_MODIFY_REQUEST_INVALID},
+         *               {@link VideoProvider#SESSION_MODIFY_REQUEST_TIMED_OUT},
+         *               {@link VideoProvider#SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE}
+         * @param requestedProfile The original request which was sent to the peer device.
+         * @param responseProfile The actual profile changes agreed to by the peer device.
+         * @see #onSendSessionModifyRequest(VideoProfile, VideoProfile)
          */
         public void receiveSessionModifyResponse(int status,
                 VideoProfile requestedProfile, VideoProfile responseProfile) {
@@ -688,14 +784,18 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
+         * Used to inform listening {@link InCallService} implementations when the
+         * {@link VideoProvider} reports a call session event.
+         * <p>
+         * Received by the {@link InCallService} via
+         * {@link InCallService.VideoCall.Callback#onCallSessionEvent(int)}.
          *
-         * Valid values are: {@link VideoProvider#SESSION_EVENT_RX_PAUSE},
-         * {@link VideoProvider#SESSION_EVENT_RX_RESUME},
-         * {@link VideoProvider#SESSION_EVENT_TX_START},
-         * {@link VideoProvider#SESSION_EVENT_TX_STOP}
-         *
-         * @param event The event.
+         * @param event The event.  Valid values are: {@link VideoProvider#SESSION_EVENT_RX_PAUSE},
+         *      {@link VideoProvider#SESSION_EVENT_RX_RESUME},
+         *      {@link VideoProvider#SESSION_EVENT_TX_START},
+         *      {@link VideoProvider#SESSION_EVENT_TX_STOP},
+         *      {@link VideoProvider#SESSION_EVENT_CAMERA_FAILURE},
+         *      {@link VideoProvider#SESSION_EVENT_CAMERA_READY}.
          */
         public void handleCallSessionEvent(int event) {
             if (mVideoCallbacks != null) {
@@ -709,7 +809,14 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
+         * Used to inform listening {@link InCallService} implementations when the dimensions of the
+         * peer's video have changed.
+         * <p>
+         * This could occur if, for example, the peer rotates their device, changing the aspect
+         * ratio of the video, or if the user switches between the back and front cameras.
+         * <p>
+         * Received by the {@link InCallService} via
+         * {@link InCallService.VideoCall.Callback#onPeerDimensionsChanged(int, int)}.
          *
          * @param width  The updated peer video width.
          * @param height The updated peer video height.
@@ -726,9 +833,18 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
+         * Used to inform listening {@link InCallService} implementations when the data usage of the
+         * video associated with the current {@link Connection} has changed.
+         * <p>
+         * This could be in response to a preview request via
+         * {@link #onRequestConnectionDataUsage()}, or as a periodic update by the
+         * {@link VideoProvider}.
+         * <p>
+         * Received by the {@link InCallService} via
+         * {@link InCallService.VideoCall.Callback#onCallDataUsageChanged(long)}.
          *
-         * @param dataUsage The updated data usage.
+         * @param dataUsage The updated data usage (in bytes).  Reported as the cumulative bytes
+         *                  used since the start of the call.
          */
         public void setCallDataUsage(long dataUsage) {
             if (mVideoCallbacks != null) {
@@ -742,9 +858,9 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
+         * @see #setCallDataUsage(long)
          *
-         * @param dataUsage The updated data usage.
+         * @param dataUsage The updated data usage (in byes).
          * @deprecated - Use {@link #setCallDataUsage(long)} instead.
          * @hide
          */
@@ -753,9 +869,18 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
+         * Used to inform listening {@link InCallService} implementations when the capabilities of
+         * the current camera have changed.
+         * <p>
+         * The {@link VideoProvider} should call this in response to
+         * {@link VideoProvider#onRequestCameraCapabilities()}, or when the current camera is
+         * changed via {@link VideoProvider#onSetCamera(String)}.
+         * <p>
+         * Received by the {@link InCallService} via
+         * {@link InCallService.VideoCall.Callback#onCameraCapabilitiesChanged(
+         * VideoProfile.CameraCapabilities)}.
          *
-         * @param cameraCapabilities The changed camera capabilities.
+         * @param cameraCapabilities The new camera capabilities.
          */
         public void changeCameraCapabilities(VideoProfile.CameraCapabilities cameraCapabilities) {
             if (mVideoCallbacks != null) {
@@ -769,15 +894,17 @@ public abstract class Connection extends Conferenceable {
         }
 
         /**
-         * Invokes callback method defined in listening {@link InCallService} implementations.
-         *
-         * Allowed values:
-         * {@link VideoProfile#QUALITY_HIGH},
-         * {@link VideoProfile#QUALITY_MEDIUM},
-         * {@link VideoProfile#QUALITY_LOW},
-         * {@link VideoProfile#QUALITY_DEFAULT}.
+         * Used to inform listening {@link InCallService} implementations when the video quality
+         * of the call has changed.
+         * <p>
+         * Received by the {@link InCallService} via
+         * {@link InCallService.VideoCall.Callback#onVideoQualityChanged(int)}.
          *
-         * @param videoQuality The updated video quality.
+         * @param videoQuality The updated video quality.  Valid values:
+         *      {@link VideoProfile#QUALITY_HIGH},
+         *      {@link VideoProfile#QUALITY_MEDIUM},
+         *      {@link VideoProfile#QUALITY_LOW},
+         *      {@link VideoProfile#QUALITY_DEFAULT}.
          */
         public void changeVideoQuality(int videoQuality) {
             if (mVideoCallbacks != null) {
diff --git a/telecomm/java/android/telecom/InCallService.java b/telecomm/java/android/telecom/InCallService.java
index e37cff7..f7f4425 100644
--- a/telecomm/java/android/telecom/InCallService.java
+++ b/telecomm/java/android/telecom/InCallService.java
@@ -20,6 +20,7 @@ import android.annotation.SdkConstant;
 import android.annotation.SystemApi;
 import android.app.Service;
 import android.content.Intent;
+import android.hardware.camera2.CameraManager;
 import android.net.Uri;
 import android.os.Handler;
 import android.os.IBinder;
@@ -387,7 +388,8 @@ public abstract class InCallService extends Service {
     }
 
     /**
-     * Class to invoke functionality related to video calls.
+     * Used to issue commands to the {@link Connection.VideoProvider} associated with a
+     * {@link Call}.
      */
     public static abstract class VideoCall {
 
@@ -410,14 +412,17 @@ public abstract class InCallService extends Service {
         public abstract void registerCallback(VideoCall.Callback callback, Handler handler);
 
         /**
-         * Clears the video call listener set via {@link #registerCallback}.
+         * Clears the video call callback set via {@link #registerCallback}.
          */
         public abstract void unregisterCallback(VideoCall.Callback callback);
 
         /**
-         * Sets the camera to be used for video recording in a video call.
+         * Sets the camera to be used for the outgoing video.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onSetCamera(String)}.
          *
-         * @param cameraId The id of the camera.
+         * @param cameraId The id of the camera (use ids as reported by
+         * {@link CameraManager#getCameraIdList()}).
          */
         public abstract void setCamera(String cameraId);
 
@@ -425,21 +430,27 @@ public abstract class InCallService extends Service {
          * Sets the surface to be used for displaying a preview of what the user's camera is
          * currently capturing.  When video transmission is enabled, this is the video signal which
          * is sent to the remote device.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onSetPreviewSurface(Surface)}.
          *
-         * @param surface The surface.
+         * @param surface The {@link Surface}.
          */
         public abstract void setPreviewSurface(Surface surface);
 
         /**
          * Sets the surface to be used for displaying the video received from the remote device.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onSetDisplaySurface(Surface)}.
          *
-         * @param surface The surface.
+         * @param surface The {@link Surface}.
          */
         public abstract void setDisplaySurface(Surface surface);
 
         /**
          * Sets the device orientation, in degrees.  Assumes that a standard portrait orientation of
          * the device is 0 degrees.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onSetDeviceOrientation(int)}.
          *
          * @param rotation The device orientation, in degrees.
          */
@@ -447,109 +458,145 @@ public abstract class InCallService extends Service {
 
         /**
          * Sets camera zoom ratio.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onSetZoom(float)}.
          *
          * @param value The camera zoom ratio.
          */
         public abstract void setZoom(float value);
 
         /**
-         * Issues a request to modify the properties of the current session.  The request is sent to
-         * the remote device where it it handled by
-         * {@link VideoCall.Callback#onSessionModifyRequestReceived}.
-         * Some examples of session modification requests: upgrade call from audio to video,
-         * downgrade call from video to audio, pause video.
+         * Issues a request to modify the properties of the current video session.
+         * <p>
+         * Example scenarios include: requesting an audio-only call to be upgraded to a
+         * bi-directional video call, turning on or off the user's camera, sending a pause signal
+         * when the {@link InCallService} is no longer the foreground application.
+         * <p>
+         * Handled by
+         * {@link Connection.VideoProvider#onSendSessionModifyRequest(VideoProfile, VideoProfile)}.
          *
          * @param requestProfile The requested call video properties.
          */
         public abstract void sendSessionModifyRequest(VideoProfile requestProfile);
 
         /**
-         * Provides a response to a request to change the current call session video
-         * properties.
-         * This is in response to a request the InCall UI has received via
-         * {@link VideoCall.Callback#onSessionModifyRequestReceived}.
-         * The response is handled on the remove device by
-         * {@link VideoCall.Callback#onSessionModifyResponseReceived}.
+         * Provides a response to a request to change the current call video session
+         * properties.  This should be called in response to a request the {@link InCallService} has
+         * received via {@link VideoCall.Callback#onSessionModifyRequestReceived}.
+         * <p>
+         * Handled by
+         * {@link Connection.VideoProvider#onSendSessionModifyResponse(VideoProfile)}.
          *
          * @param responseProfile The response call video properties.
          */
         public abstract void sendSessionModifyResponse(VideoProfile responseProfile);
 
         /**
-         * Issues a request to the video provider to retrieve the camera capabilities.
-         * Camera capabilities are reported back to the caller via
-         * {@link VideoCall.Callback#onCameraCapabilitiesChanged(CameraCapabilities)}.
+         * Issues a request to the {@link Connection.VideoProvider} to retrieve the capabilities
+         * of the current camera.  The current camera is selected using
+         * {@link VideoCall#setCamera(String)}.
+         * <p>
+         * Camera capabilities are reported to the caller via
+         * {@link VideoCall.Callback#onCameraCapabilitiesChanged(VideoProfile.CameraCapabilities)}.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onRequestCameraCapabilities()}.
          */
         public abstract void requestCameraCapabilities();
 
         /**
-         * Issues a request to the video telephony framework to retrieve the cumulative data usage for
-         * the current call.  Data usage is reported back to the caller via
-         * {@link VideoCall.Callback#onCallDataUsageChanged}.
+         * Issues a request to the {@link Connection.VideoProvider} to retrieve the cumulative data
+         * usage for the video component of the current call (in bytes).  Data usage is reported
+         * to the caller via {@link VideoCall.Callback#onCallDataUsageChanged}.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onRequestConnectionDataUsage()}.
          */
         public abstract void requestCallDataUsage();
 
         /**
-         * Provides the video telephony framework with the URI of an image to be displayed to remote
-         * devices when the video signal is paused.
+         * Provides the {@link Connection.VideoProvider} with the {@link Uri} of an image to be
+         * displayed to the peer device when the video signal is paused.
+         * <p>
+         * Handled by {@link Connection.VideoProvider#onSetPauseImage(Uri)}.
          *
          * @param uri URI of image to display.
          */
         public abstract void setPauseImage(Uri uri);
 
         /**
-         * Callback class which invokes callbacks after video call actions occur.
+         * The {@link InCallService} extends this class to provide a means of receiving callbacks
+         * from the {@link Connection.VideoProvider}.<p>
+         * When the {@link InCallService} receives the
+         * {@link Call.Callback#onVideoCallChanged(Call, VideoCall)} callback, it should create an
+         * instance its {@link VideoCall.Callback} implementation and set it on the
+         * {@link VideoCall} using {@link VideoCall#registerCallback(Callback)}.
          */
         public static abstract class Callback {
             /**
-             * Called when a session modification request is received from the remote device.
-             * The remote request is sent via
-             * {@link Connection.VideoProvider#onSendSessionModifyRequest}. The InCall UI
-             * is responsible for potentially prompting the user whether they wish to accept the new
-             * call profile (e.g. prompt user if they wish to accept an upgrade from an audio to a
-             * video call) and should call
-             * {@link Connection.VideoProvider#onSendSessionModifyResponse} to indicate
-             * the video settings the user has agreed to.
+             * Called when the {@link Connection.VideoProvider} receives a session modification
+             * request is received from the peer device.
+             * <p>
+             * The {@link InCallService} may potentially prompt the user to confirm whether they
+             * wish to accept the request, or decide to automatically accept the request.  In either
+             * case the {@link InCallService} should call
+             * {@link VideoCall#sendSessionModifyResponse(VideoProfile)} to indicate the video
+             * profile agreed upon.
+             * <p>
+             * Callback originates from
+             * {@link Connection.VideoProvider#receiveSessionModifyRequest(VideoProfile)}.
              *
-             * @param videoProfile The requested video call profile.
+             * @param videoProfile The requested video profile.
              */
             public abstract void onSessionModifyRequestReceived(VideoProfile videoProfile);
 
             /**
-             * Called when a response to a session modification request is received from the remote
-             * device. The remote InCall UI sends the response using
-             * {@link Connection.VideoProvider#onSendSessionModifyResponse}.
+             * Called when the {@link Connection.VideoProvider} receives a response to a session
+             * modification request previously sent to the peer device.
+             * <p>
+             * The new video state should not be considered active by the {@link InCallService}
+             * until the {@link Call} video state changes (the
+             * {@link Call.Callback#onDetailsChanged(Call, Call.Details)} callback is triggered
+             * when the video state changes).
+             * <p>
+             * Callback originates from
+             * {@link Connection.VideoProvider#receiveSessionModifyResponse(int, VideoProfile,
+             *      VideoProfile)}.
              *
              * @param status Status of the session modify request.  Valid values are
-             *               {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS},
-             *               {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_FAIL},
-             *               {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_INVALID}
-             * @param requestedProfile The original request which was sent to the remote device.
-             * @param responseProfile The actual profile changes made by the remote device.
+             *      {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS},
+             *      {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_FAIL},
+             *      {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_INVALID},
+             *      {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_TIMED_OUT},
+             *      {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE}.
+             * @param requestedProfile The original request which was sent to the peer device.
+             * @param responseProfile The actual profile changes made by the peer device.
              */
             public abstract void onSessionModifyResponseReceived(int status,
                     VideoProfile requestedProfile, VideoProfile responseProfile);
 
             /**
-             * Handles events related to the current session which the client may wish to handle.
-             * These are separate from requested changes to the session due to the underlying
-             * protocol or connection.
+             * Handles events related to the current video session which the {@link InCallService}
+             * may wish to handle. These are separate from requested changes to the session due to
+             * the underlying protocol or connection.
+             * <p>
+             * Callback originates from
+             * {@link Connection.VideoProvider#handleCallSessionEvent(int)}.
              *
-             * Valid values are:
-             * {@link Connection.VideoProvider#SESSION_EVENT_RX_PAUSE},
-             * {@link Connection.VideoProvider#SESSION_EVENT_RX_RESUME},
-             * {@link Connection.VideoProvider#SESSION_EVENT_TX_START},
-             * {@link Connection.VideoProvider#SESSION_EVENT_TX_STOP},
-             * {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_FAILURE},
-             * {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_READY}
-             *
-             * @param event The event.
+             * @param event The event.  Valid values are:
+             *      {@link Connection.VideoProvider#SESSION_EVENT_RX_PAUSE},
+             *      {@link Connection.VideoProvider#SESSION_EVENT_RX_RESUME},
+             *      {@link Connection.VideoProvider#SESSION_EVENT_TX_START},
+             *      {@link Connection.VideoProvider#SESSION_EVENT_TX_STOP},
+             *      {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_FAILURE},
+             *      {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_READY}.
              */
             public abstract void onCallSessionEvent(int event);
 
             /**
-             * Handles a change to the video dimensions from the remote caller (peer). This could
-             * happen if, for example, the peer changes orientation of their device.
+             * Handles a change to the video dimensions from the peer device. This could happen if,
+             * for example, the peer changes orientation of their device, or switches cameras.
+             * <p>
+             * Callback originates from
+             * {@link Connection.VideoProvider#changePeerDimensions(int, int)}.
              *
              * @param width  The updated peer video width.
              * @param height The updated peer video height.
@@ -558,20 +605,41 @@ public abstract class InCallService extends Service {
 
             /**
              * Handles a change to the video quality.
+             * <p>
+             * Callback originates from {@link Connection.VideoProvider#changeVideoQuality(int)}.
              *
-             * @param videoQuality  The updated peer video quality.
+             * @param videoQuality  The updated peer video quality.  Valid values:
+             *      {@link VideoProfile#QUALITY_HIGH},
+             *      {@link VideoProfile#QUALITY_MEDIUM},
+             *      {@link VideoProfile#QUALITY_LOW},
+             *      {@link VideoProfile#QUALITY_DEFAULT}.
              */
             public abstract void onVideoQualityChanged(int videoQuality);
 
             /**
-             * Handles an update to the total data used for the current session.
+             * Handles an update to the total data used for the current video session.
+             * <p>
+             * Used by the {@link Connection.VideoProvider} in response to
+             * {@link VideoCall#requestCallDataUsage()}.  May also be called periodically by the
+             * {@link Connection.VideoProvider}.
+             * <p>
+             * Callback originates from {@link Connection.VideoProvider#setCallDataUsage(long)}.
              *
-             * @param dataUsage The updated data usage.
+             * @param dataUsage The updated data usage (in bytes).
              */
             public abstract void onCallDataUsageChanged(long dataUsage);
 
             /**
-             * Handles a change in camera capabilities.
+             * Handles a change in the capabilities of the currently selected camera.
+             * <p>
+             * Used by the {@link Connection.VideoProvider} in response to
+             * {@link VideoCall#requestCameraCapabilities()}.  The {@link Connection.VideoProvider}
+             * may also report the camera capabilities after a call to
+             * {@link VideoCall#setCamera(String)}.
+             * <p>
+             * Callback originates from
+             * {@link Connection.VideoProvider#changeCameraCapabilities(
+             *      VideoProfile.CameraCapabilities)}.
              *
              * @param cameraCapabilities The changed camera capabilities.
              */