Telecom API council changes.

- adding more javadocs.
- fixing javadoc on isEnabled
- renaming to CONFIGURE_PHONE_ACCOUNT

Bug: 21573551
Change-Id: Ice035b8573a08ea18181a73c9e9a462520a934f1

7 files changed, 127 insertions, 18 deletions

diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java
index 6055211..721b718 100644
--- a/telecomm/java/android/telecom/Connection.java
+++ b/telecomm/java/android/telecom/Connection.java
@@ -40,7 +40,8 @@ import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * Represents a connection to a remote endpoint that carries voice traffic.
+ * Represents a phone call or connection to a remote endpoint that carries voice and/or video
+ * traffic.
  * <p>
  * Implementations create a custom subclass of {@code Connection} and return it to the framework
  * as the return value of
@@ -53,21 +54,52 @@ import java.util.concurrent.ConcurrentHashMap;
  */
 public abstract class Connection extends Conferenceable {
 
+    /**
+     * The connection is initializing. This is generally the first state for a {@code Connection}
+     * returned by a {@link ConnectionService}.
+     */
     public static final int STATE_INITIALIZING = 0;
 
+    /**
+     * The connection is new and not connected.
+     */
     public static final int STATE_NEW = 1;
 
+    /**
+     * An incoming connection is in the ringing state. During this state, the user's ringer or
+     * vibration feature will be activated.
+     */
     public static final int STATE_RINGING = 2;
 
+    /**
+     * An outgoing connection is in the dialing state. In this state the other party has not yet
+     * answered the call and the user traditionally hears a ringback tone.
+     */
     public static final int STATE_DIALING = 3;
 
+    /**
+     * A connection is active. Both parties are connected to the call and can actively communicate.
+     */
     public static final int STATE_ACTIVE = 4;
 
+    /**
+     * A connection is on hold.
+     */
     public static final int STATE_HOLDING = 5;
 
+    /**
+     * A connection has been disconnected. This is the final state once the user has been
+     * disconnected from a call either locally, remotely or by an error in the service.
+     */
     public static final int STATE_DISCONNECTED = 6;
 
-    /** Connection can currently be put on hold or unheld. */
+    /**
+     * Connection can currently be put on hold or unheld. This is distinct from
+     * {@link #CAPABILITY_SUPPORT_HOLD} in that although a connection may support 'hold' most times,
+     * it does not at the moment support the function. This can be true while the call is in the
+     * state {@link #STATE_DIALING}, for example. During this condition, an in-call UI may
+     * display a disabled 'hold' button.
+     */
     public static final int CAPABILITY_HOLD = 0x00000001;
 
     /** Connection supports the hold feature. */
diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java
index 1e8ae88..d2e7a74 100644
--- a/telecomm/java/android/telecom/ConnectionService.java
+++ b/telecomm/java/android/telecom/ConnectionService.java
@@ -41,8 +41,8 @@ import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * {@code ConnectionService} is an abstract service that should be implemented by any app which can
- * make phone calls and want those calls to be integrated into the built-in phone app.
+ * An abstract service that should be implemented by any apps which can make phone calls (VoIP or
+ * otherwise) and want those calls to be integrated into the built-in phone app.
  * Once implemented, the {@code ConnectionService} needs two additional steps before it will be
  * integrated into the phone app:
  * <p>
@@ -62,7 +62,7 @@ import java.util.concurrent.ConcurrentHashMap;
  * <br/>
  * See {@link PhoneAccount} and {@link TelecomManager#registerPhoneAccount} for more information.
  * <p>
- * Once registered and enabled by the user in the dialer settings, telecom will bind to a
+ * Once registered and enabled by the user in the phone app settings, telecom will bind to a
  * {@code ConnectionService} implementation when it wants that {@code ConnectionService} to place
  * a call or the service has indicated that is has an incoming call through
  * {@link TelecomManager#addNewIncomingCall}. The {@code ConnectionService} can then expect a call
diff --git a/telecomm/java/android/telecom/InCallService.java b/telecomm/java/android/telecom/InCallService.java
index 0f8ac63..19c613d 100644
--- a/telecomm/java/android/telecom/InCallService.java
+++ b/telecomm/java/android/telecom/InCallService.java
@@ -248,7 +248,7 @@ public abstract class InCallService extends Service {
     }
 
     /**
-     * Obtains the current list of {@code Call}s to be displayed by this in-call experience.
+     * Obtains the current list of {@code Call}s to be displayed by this in-call service.
      *
      * @return A list of the relevant {@code Call}s.
      */
diff --git a/telecomm/java/android/telecom/PhoneAccount.java b/telecomm/java/android/telecom/PhoneAccount.java
index a25d327..df6fa2e 100644
--- a/telecomm/java/android/telecom/PhoneAccount.java
+++ b/telecomm/java/android/telecom/PhoneAccount.java
@@ -412,7 +412,7 @@ public final class PhoneAccount implements Parcelable {
      * bit mask.
      *
      * @param capability The capabilities to check.
-     * @return {@code True} if the phone account has the capability.
+     * @return {@code true} if the phone account has the capability.
      */
     public boolean hasCapabilities(int capability) {
         return (mCapabilities & capability) == capability;
@@ -455,9 +455,10 @@ public final class PhoneAccount implements Parcelable {
     }
 
     /**
-     * Indicates whether the user has enabled this phone account or not {@code PhoneAccounts}.
+     * Indicates whether the user has enabled this {@code PhoneAccount} or not. This value is only
+     * populated for {@code PhoneAccount}s returned by {@link TelecomManager#getPhoneAccount}.
      *
-     * @return The {@code true} if the account is enabled by the user, {@code false} otherwise.
+     * @return {@code true} if the account is enabled by the user, {@code false} otherwise.
      */
     public boolean isEnabled() {
         return mIsEnabled;
@@ -468,7 +469,7 @@ public final class PhoneAccount implements Parcelable {
      * scheme.
      *
      * @param uriScheme The URI scheme to check.
-     * @return {@code True} if the {@code PhoneAccount} supports calls to/from addresses with the
+     * @return {@code true} if the {@code PhoneAccount} supports calls to/from addresses with the
      * specified URI scheme.
      */
     public boolean supportsUriScheme(String uriScheme) {
diff --git a/telecomm/java/android/telecom/RemoteConference.java b/telecomm/java/android/telecom/RemoteConference.java
index c2261c3..ae5cd46 100644
--- a/telecomm/java/android/telecom/RemoteConference.java
+++ b/telecomm/java/android/telecom/RemoteConference.java
@@ -32,25 +32,90 @@ import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.CopyOnWriteArraySet;
 
 /**
- * A conference provided to a {@link ConnectionService} by another {@code ConnectionService}
- * running in a different process.
+ * A conference provided to a {@link ConnectionService} by another {@code ConnectionService} through
+ * {@link ConnectionService#conferenceRemoteConnections}. Once created, a {@code RemoteConference}
+ * can be used to control the conference call or monitor changes through
+ * {@link RemoteConnection.Callback}.
  *
  * @see ConnectionService#onRemoteConferenceAdded
  */
 public final class RemoteConference {
 
+    /**
+     * Callback base class for {@link RemoteConference}.
+     */
     public abstract static class Callback {
+        /**
+         * Invoked when the state of this {@code RemoteConferece} has changed. See
+         * {@link #getState()}.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         * @param oldState The previous state of the {@code RemoteConference}.
+         * @param newState The new state of the {@code RemoteConference}.
+         */
         public void onStateChanged(RemoteConference conference, int oldState, int newState) {}
+
+        /**
+         * Invoked when this {@code RemoteConference} is disconnected.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         * @param disconnectCause The ({@see DisconnectCause}) associated with this failed
+         *     conference.
+         */
         public void onDisconnected(RemoteConference conference, DisconnectCause disconnectCause) {}
+
+        /**
+         * Invoked when a {@link RemoteConnection} is added to the conference call.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         * @param connection The {@link RemoteConnection} being added.
+         */
         public void onConnectionAdded(RemoteConference conference, RemoteConnection connection) {}
+
+        /**
+         * Invoked when a {@link RemoteConnection} is removed from the conference call.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         * @param connection The {@link RemoteConnection} being removed.
+         */
         public void onConnectionRemoved(RemoteConference conference, RemoteConnection connection) {}
+
+        /**
+         * Indicates that the call capabilities of this {@code RemoteConference} have changed.
+         * See {@link #getConnectionCapabilities()}.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         * @param connectionCapabilities The new capabilities of the {@code RemoteConference}.
+         */
         public void onConnectionCapabilitiesChanged(
                 RemoteConference conference,
                 int connectionCapabilities) {}
+
+        /**
+         * Invoked when the set of {@link RemoteConnection}s which can be added to this conference
+         * call have changed.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         * @param conferenceableConnections The list of conferenceable {@link RemoteConnection}s.
+         */
         public void onConferenceableConnectionsChanged(
                 RemoteConference conference,
                 List<RemoteConnection> conferenceableConnections) {}
+
+        /**
+         * Indicates that this {@code RemoteConference} has been destroyed. No further requests
+         * should be made to the {@code RemoteConference}, and references to it should be cleared.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         */
         public void onDestroyed(RemoteConference conference) {}
+
+        /**
+         * Handles changes to the {@code RemoteConference} extras.
+         *
+         * @param conference The {@code RemoteConference} invoking this method.
+         * @param extras The extras containing other information associated with the conference.
+         */
         public void onExtrasChanged(RemoteConference conference, @Nullable Bundle extras) {}
     }
 
diff --git a/telecomm/java/android/telecom/RemoteConnection.java b/telecomm/java/android/telecom/RemoteConnection.java
index 8f7b82f..f960959 100644
--- a/telecomm/java/android/telecom/RemoteConnection.java
+++ b/telecomm/java/android/telecom/RemoteConnection.java
@@ -45,6 +45,9 @@ import java.util.concurrent.ConcurrentHashMap;
  */
 public final class RemoteConnection {
 
+    /**
+     * Callback base class for {@link RemoteConnection}.
+     */
     public static abstract class Callback {
         /**
          * Invoked when the state of this {@code RemoteConnection} has changed. See
@@ -200,7 +203,7 @@ public final class RemoteConnection {
                 RemoteConference conference) {}
 
         /**
-         * Handles changes to the {@code RemoteConference} extras.
+         * Handles changes to the {@code RemoteConnection} extras.
          *
          * @param connection The {@code RemoteConnection} invoking this method.
          * @param extras The extras containing other information associated with the connection.
diff --git a/telecomm/java/android/telecom/TelecomManager.java b/telecomm/java/android/telecom/TelecomManager.java
index 11f206a..a30e1c0 100644
--- a/telecomm/java/android/telecom/TelecomManager.java
+++ b/telecomm/java/android/telecom/TelecomManager.java
@@ -67,11 +67,19 @@ public class TelecomManager {
     public static final String ACTION_NEW_UNKNOWN_CALL = "android.telecom.action.NEW_UNKNOWN_CALL";
 
     /**
-     * The {@link android.content.Intent} action used to configure a
-     * {@link android.telecom.ConnectionService}.
-     */
-    public static final String ACTION_CONNECTION_SERVICE_CONFIGURE =
-            "android.telecom.action.CONNECTION_SERVICE_CONFIGURE";
+     * An {@link android.content.Intent} action sent by the telecom framework to start a
+     * configuration dialog for a registered {@link PhoneAccount}. There is no default dialog
+     * and each app that registers a {@link PhoneAccount} should provide one if desired.
+     * <p>
+     * A user can access the list of enabled {@link android.telecom.PhoneAccount}s through the Phone
+     * app's settings menu. For each entry, the settings app will add a click action. When
+     * triggered, the click-action will start this intent along with the extra
+     * {@link #EXTRA_PHONE_ACCOUNT_HANDLE} to indicate the {@link PhoneAccount} to configure. If the
+     * {@link PhoneAccount} package does not register an {@link android.app.Activity} for this
+     * intent, then it will not be sent.
+     */
+    public static final String ACTION_CONFIGURE_PHONE_ACCOUNT =
+            "android.telecom.action.CONFIGURE_PHONE_ACCOUNT";
 
     /**
      * The {@link android.content.Intent} action used to show the call accessibility settings page.