1 files changed, 43 insertions, 22 deletions

diff --git a/telecomm/java/android/telecom/Conference.java b/telecomm/java/android/telecom/Conference.java
index 0227d27180b5..a01208205859 100644
--- a/telecomm/java/android/telecom/Conference.java
+++ b/telecomm/java/android/telecom/Conference.java
@@ -24,6 +24,7 @@ import android.telecom.Connection.VideoProvider;
 import android.util.ArraySet;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import java.util.Locale;
@@ -164,7 +165,6 @@ public abstract class Conference extends Conferenceable {
      * {@link Connection} for valid values.
      *
      * @return A bitmask of the properties of the conference call.
-     * @hide
      */
     public final int getConnectionProperties() {
         return mConnectionProperties;
@@ -256,60 +256,63 @@ public abstract class Conference extends Conferenceable {
     }
 
     /**
-     * Invoked when the Conference and all it's {@link Connection}s should be disconnected.
+     * Notifies the {@link Conference} when the Conference and all it's {@link Connection}s should
+     * be disconnected.
      */
     public void onDisconnect() {}
 
     /**
-     * Invoked when the specified {@link Connection} should be separated from the conference call.
+     * Notifies the {@link Conference} when the specified {@link Connection} should be separated
+     * from the conference call.
      *
      * @param connection The connection to separate.
      */
     public void onSeparate(Connection connection) {}
 
     /**
-     * Invoked when the specified {@link Connection} should merged with the conference call.
+     * Notifies the {@link Conference} when the specified {@link Connection} should merged with the
+     * conference call.
      *
      * @param connection The {@code Connection} to merge.
      */
     public void onMerge(Connection connection) {}
 
     /**
-     * Invoked when the conference should be put on hold.
+     * Notifies the {@link Conference} when it should be put on hold.
      */
     public void onHold() {}
 
     /**
-     * Invoked when the conference should be moved from hold to active.
+     * Notifies the {@link Conference} when it should be moved from a held to active state.
      */
     public void onUnhold() {}
 
     /**
-     * Invoked when the child calls should be merged. Only invoked if the conference contains the
-     * capability {@link Connection#CAPABILITY_MERGE_CONFERENCE}.
+     * Notifies the {@link Conference} when the child calls should be merged.  Only invoked if the
+     * conference contains the capability {@link Connection#CAPABILITY_MERGE_CONFERENCE}.
      */
     public void onMerge() {}
 
     /**
-     * Invoked when the child calls should be swapped. Only invoked if the conference contains the
-     * capability {@link Connection#CAPABILITY_SWAP_CONFERENCE}.
+     * Notifies the {@link Conference} when the child calls should be swapped. Only invoked if the
+     * conference contains the capability {@link Connection#CAPABILITY_SWAP_CONFERENCE}.
      */
     public void onSwap() {}
 
     /**
-     * Notifies this conference of a request to play a DTMF tone.
+     * Notifies the {@link Conference} of a request to play a DTMF tone.
      *
      * @param c A DTMF character.
      */
     public void onPlayDtmfTone(char c) {}
 
     /**
-     * Notifies this conference of a request to stop any currently playing DTMF tones.
+     * Notifies the {@link Conference} of a request to stop any currently playing DTMF tones.
      */
     public void onStopDtmfTone() {}
 
     /**
-     * Notifies this conference that the {@link #getAudioState()} property has a new value.
+     * Notifies the {@link Conference} that the {@link #getAudioState()} property has a new value.
      *
      * @param state The new call audio state.
      * @deprecated Use {@link #onCallAudioStateChanged(CallAudioState)} instead.
@@ -320,14 +323,15 @@ public abstract class Conference extends Conferenceable {
     public void onAudioStateChanged(AudioState state) {}
 
     /**
-     * Notifies this conference that the {@link #getCallAudioState()} property has a new value.
+     * Notifies the {@link Conference} that the {@link #getCallAudioState()} property has a new
+     * value.
      *
      * @param state The new call audio state.
      */
     public void onCallAudioStateChanged(CallAudioState state) {}
 
     /**
-     * Notifies this conference that a connection has been added to it.
+     * Notifies the {@link Conference} that a {@link Connection} has been added to it.
      *
      * @param connection The newly added connection.
      */
@@ -396,7 +400,6 @@ public abstract class Conference extends Conferenceable {
      * {@link Connection} for valid values.
      *
      * @param connectionProperties A bitmask of the {@code Properties} of the conference call.
-     * @hide
      */
     public final void setConnectionProperties(int connectionProperties) {
         if (connectionProperties != mConnectionProperties) {
@@ -681,8 +684,11 @@ public abstract class Conference extends Conferenceable {
      * New or existing keys are replaced in the {@code Conference} extras.  Keys which are no longer
      * in the new extras, but were present the last time {@code setExtras} was called are removed.
      * <p>
+     * Alternatively you may use the {@link #putExtras(Bundle)}, and
+     * {@link #removeExtras(String...)} methods to modify the extras.
+     * <p>
      * No assumptions should be made as to how an In-Call UI or service will handle these extras.
-     * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
+     * Keys should be fully qualified (e.g., com.example.extras.MY_EXTRA) to avoid conflicts.
      *
      * @param extras The extras associated with this {@code Conference}.
      */
@@ -727,7 +733,6 @@ public abstract class Conference extends Conferenceable {
      * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
      *
      * @param extras The extras to add.
-     * @hide
      */
     public final void putExtras(@NonNull Bundle extras) {
         if (extras == null) {
@@ -790,10 +795,9 @@ public abstract class Conference extends Conferenceable {
     }
 
     /**
-     * Removes an extra from this {@link Conference}.
+     * Removes extras from this {@link Conference}.
      *
-     * @param keys The key of the extra key to remove.
-     * @hide
+     * @param keys The keys of the extras to remove.
      */
     public final void removeExtras(List<String> keys) {
         if (keys == null || keys.isEmpty()) {
@@ -815,7 +819,25 @@ public abstract class Conference extends Conferenceable {
     }
 
     /**
+     * Removes extras from this {@link Conference}.
+     *
+     * @param keys The keys of the extras to remove.
+     */
+    public final void removeExtras(String ... keys) {
+        removeExtras(Arrays.asList(keys));
+    }
+
+    /**
      * Returns the extras associated with this conference.
+     * <p>
+     * Extras should be updated using {@link #putExtras(Bundle)} and {@link #removeExtras(List)}.
+     * <p>
+     * Telecom or an {@link InCallService} can also update the extras via
+     * {@link android.telecom.Call#putExtras(Bundle)}, and
+     * {@link Call#removeExtras(List)}.
+     * <p>
+     * The conference is notified of changes to the extras made by Telecom or an
+     * {@link InCallService} by {@link #onExtrasChanged(Bundle)}.
      *
      * @return The extras associated with this connection.
      */
@@ -832,7 +854,6 @@ public abstract class Conference extends Conferenceable {
      * {@link Call#removeExtras(List)}.
      *
      * @param extras The new extras bundle.
-     * @hide
      */
     public void onExtrasChanged(Bundle extras) {}