More updates to javadocs for Telecom APIs.

Change-Id: I8f8389f521c0d654c9bfdc3ad9670be0d118f480

telecomm/java/android/telecom/AudioState.java

@@ -22,7 +22,8 @@ import android.os.Parcelable;
 import java.util.Locale;
 
 /**
- *  Encapsulates all audio states during a call.
+ *  Encapsulates the telecom audio state, including the current audio routing, supported audio
+ *  routing and mute.
  */
 public final class AudioState implements Parcelable {
     /** Direct the audio stream through the device's earpiece. */
@@ -53,10 +54,10 @@ public final class AudioState implements Parcelable {
     /** True if the call is muted, false otherwise. */
     public final boolean isMuted;
 
-    /** The route to use for the audio stream. */
+    /** The current audio route being used. */
     public final int route;
 
-    /** Bit vector of all routes supported by this call. */
+    /** Bit mask of all routes supported by this call. */
     public final int supportedRouteMask;
 
     public AudioState(boolean isMuted, int route, int supportedRouteMask) {

telecomm/java/android/telecom/DisconnectCause.java

@@ -25,9 +25,10 @@ import java.util.Objects;
 
 /**
  * Describes the cause of a disconnected call. This always includes a code describing the generic
- * cause of the disconnect. Optionally, it may include a localized label and/or localized description
- * to display to the user which is provided by the {@link ConnectionService}. It also may contain a
- * reason for the the disconnect, which is intended for logging and not for display to the user.
+ * cause of the disconnect. Optionally, it may include a label and/or description to display to the
+ * user. It is the responsibility of the {@link ConnectionService} to provide localized versions of
+ * the label and description. It also may contain a reason for the disconnect, which is intended for
+ * logging and not for display to the user.
  */
 public final class DisconnectCause implements Parcelable {
 
@@ -85,6 +86,7 @@ public final class DisconnectCause implements Parcelable {
 
     /**
      * Creates a new DisconnectCause.
+     *
      * @param label The localized label to show to the user to explain the disconnect.
      * @param code The code for the disconnect cause.
      * @param description The localized description to show to the user to explain the disconnect.

telecomm/java/android/telecom/PhoneAccountHandle.java

@@ -23,7 +23,16 @@ import android.os.Parcelable;
 import java.util.Objects;
 
 /**
- * The unique identifier for a {@link PhoneAccount}.
+ * The unique identifier for a {@link PhoneAccount}. A {@code PhoneAccountHandle} is made of two
+ * parts:
+ * <ul>
+ *  <li>The component name of the associated {@link ConnectionService}.</li>
+ *  <li>A string identifier that is unique across {@code PhoneAccountHandle}s with the same
+ *      component name.</li>
+ * </ul>
+ *
+ * See {@link PhoneAccount},
+ * {@link TelecomManager#registerPhoneAccount TelecomManager.registerPhoneAccount}.
  */
 public class PhoneAccountHandle implements Parcelable {
     private ComponentName mComponentName;

telecomm/java/android/telecom/TelecomManager.java

@@ -30,7 +30,17 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * Provides access to Telecom-related functionality.
+ * Provides access to information about active calls and registration/call-management functionality.
+ * Apps can use methods in this class to determine the current call state. Apps can also register new
+ * {@link PhoneAccount}s and get a listing of existing {@link PhoneAccount}s.
+ * <p>
+ * Apps do not instantiate this class directly; instead, they retrieve a reference to an instance
+ * through {@link Context#getSystemService Context.getSystemService(Context.TELECOM_SERVICE)}.
+ * <p>
+ * Note that access to some telecom information is permission-protected. Your app cannot access the
+ * protected information or gain access to protected functionality unless it has the appropriate
+ * permissions declared in its manifest file. Where permissions apply, they are noted in the method
+ * descriptions.
  */
 public class TelecomManager {
 
@@ -582,7 +592,16 @@ public class TelecomManager {
     }
 
     /**
-     * Register a {@link PhoneAccount} for use by the system.
+     * Register a {@link PhoneAccount} for use by the system. When registering
+     * {@link PhoneAccount}s, existing registrations will be overwritten if the
+     * {@link PhoneAccountHandle} matches that of a {@link PhoneAccount} which is already
+     * registered. Once registered, the {@link PhoneAccount} is listed to the user as an option
+     * when placing calls. The user may still need to enable the {@link PhoneAccount} within
+     * the phone app settings before the account is usable.
+     * <p>
+     * A {@link SecurityException} will be thrown if an app tries to register a
+     * {@link PhoneAccountHandle} where the package name specified within
+     * {@link PhoneAccountHandle#getComponentName()} does not match the package name of the app.
      *
      * @param account The complete {@link PhoneAccount}.
      */