Merge "Even more javadocs for telecom." into lmp-mr1-dev

2 files changed, 38 insertions, 19 deletions

diff --git a/telecomm/java/android/telecom/GatewayInfo.java b/telecomm/java/android/telecom/GatewayInfo.java
index 583c3e2..7105602 100644
--- a/telecomm/java/android/telecom/GatewayInfo.java
+++ b/telecomm/java/android/telecom/GatewayInfo.java
@@ -23,12 +23,16 @@ import android.os.Parcelable;
 import android.text.TextUtils;
 
 /**
- * When calls are made, they may contain gateway information for services which route phone calls
- * through their own service/numbers. The data consists of a number to call and the package name of
- * the service. This data is used in two ways:
+ * Encapsulated gateway address information for outgoing call. When calls are made, the system
+ * provides a facility to specify two addresses for the call: one to display as the address being
+ * dialed and a separate (gateway) address to actually dial. Telecom provides this information to
+ * {@link ConnectionService}s when placing the call as an instance of {@code GatewayInfo}.
+ * <p>
+ * The data consists of an address to call, an address to display and the package name of the
+ * service. This data is used in two ways:
  * <ol>
- * <li> Call the appropriate routing number
- * <li> Display information about how the call is being routed to the user
+ * <li> Call the appropriate gateway address.
+ * <li> Display information about how the call is being routed to the user.
  * </ol>
  */
 public class GatewayInfo implements Parcelable {
@@ -46,31 +50,39 @@ public class GatewayInfo implements Parcelable {
     }
 
     /**
-     * Package name of the gateway provider service. used to place the call with.
+     * Package name of the gateway provider service that provided the gateway information.
+     * This can be used to identify the gateway address source and to load an appropriate icon when
+     * displaying gateway information in the in-call UI.
      */
     public String getGatewayProviderPackageName() {
         return mGatewayProviderPackageName;
     }
 
     /**
-     * Gateway provider address to use when actually placing the call.
+     * Returns the gateway address to dial when placing the call.
      */
     public Uri getGatewayAddress() {
         return mGatewayAddress;
     }
 
     /**
-     * The actual call address that the user is trying to connect to via the gateway.
+     * Returns the address that the user is trying to connect to via the gateway.
      */
     public Uri getOriginalAddress() {
         return mOriginalAddress;
     }
 
+    /**
+     * Indicates whether this {@code GatewayInfo} instance contains any data. A returned value of
+     * false indicates that no gateway number is being used for the call.
+     */
     public boolean isEmpty() {
         return TextUtils.isEmpty(mGatewayProviderPackageName) || mGatewayAddress == null;
     }
 
-    /** Implement the Parcelable interface */
+    /**
+     * The Parcelable interface.
+     * */
     public static final Parcelable.Creator<GatewayInfo> CREATOR =
             new Parcelable.Creator<GatewayInfo> () {
 
diff --git a/telecomm/java/android/telecom/PhoneCapabilities.java b/telecomm/java/android/telecom/PhoneCapabilities.java
index 9c67503..3d3c6bd 100644
--- a/telecomm/java/android/telecom/PhoneCapabilities.java
+++ b/telecomm/java/android/telecom/PhoneCapabilities.java
@@ -17,8 +17,8 @@
 package android.telecom;
 
 /**
- * Defines capabilities a phone call can support, such as conference calling and video telephony.
- * Also defines properties of a phone call, such as whether it is using VoLTE technology.
+ * Defines capabilities for {@link Connection}s and {@link Conference}s such as hold, swap, and
+ * merge.
  */
 public final class PhoneCapabilities {
     /** Call can currently be put on hold or unheld. */
@@ -28,15 +28,22 @@ public final class PhoneCapabilities {
     public static final int SUPPORT_HOLD       = 0x00000002;
 
     /**
-     * Calls within a conference can be merged. Some connection services create a conference call
-     * only after two calls have been merged.  However, a conference call can also be added the
-     * moment there are more than one call. CDMA calls are implemented in this way because the call
-     * actions are more limited when more than one call exists. This flag allows merge to be exposed
-     * as a capability on the conference call instead of individual calls.
+     * Calls within a conference can be merged. A {@link ConnectionService} has the option to
+     * add a {@link Conference} call before the child {@link Connection}s are merged. This is how
+     * CDMA-based {@link Connection}s are implemented. For these unmerged {@link Conference}s, this
+     * capability allows a merge button to be shown while the conference call is in the foreground
+     * of the in-call UI.
+     * <p>
+     * This is only intended for use by a {@link Conference}.
      */
     public static final int MERGE_CONFERENCE   = 0x00000004;
 
-    /** Calls withing a conference can be swapped between foreground and background. */
+    /**
+     * Calls within a conference can be swapped between foreground and background.
+     * See {@link #MERGE_CONFERENCE} for additional information.
+     * <p>
+     * This is only intended for use by a {@link Conference}.
+     */
     public static final int SWAP_CONFERENCE    = 0x00000008;
 
     /** Call currently supports adding another call to this one. */
@@ -49,8 +56,8 @@ public final class PhoneCapabilities {
     public static final int MUTE               = 0x00000040;
 
     /**
-     * Call supports conference call management. This capability only applies to conference calls
-     * which can have other calls as children.
+     * Call supports conference call management. This capability only applies to {@link Conference}
+     * calls which can have {@link Connection}s as children.
      */
     public static final int MANAGE_CONFERENCE = 0x00000080;