Telecom API doc cleanup.

InCallService - remove references to roles cut in Q release.
TelecomManager - make it more clear how to use the silenceRinger method
and under which conditions it should be used.

Test: Compile; docs only.
Fixes: 130285730
Change-Id: I55f9c2df119140666f8167e8521a4372d1108e7a

telecomm/java/android/telecom/InCallService.java

@@ -41,26 +41,12 @@ import java.util.List;
 /**
  * This service is implemented by an app that wishes to provide functionality for managing
  * phone calls.
- * <p>
- * There are three types of apps which Telecom can bind to when there exists a live (active or
- * incoming) call:
- * <ol>
- *     <li>Default Dialer/Phone app - the default dialer/phone app is one which provides the
- *     in-call user interface while the device is in a call.  A device is bundled with a system
- *     provided default dialer/phone app.  The user may choose a single app to take over this role
- *     from the system app.</li>
- *     <li>Default Car-mode Dialer/Phone app - the default car-mode dialer/phone app is one which
- *     provides the in-call user interface while the device is in a call and the device is in car
- *     mode.  The user may choose a single app to fill this role.</li>
- *     <li>Call Companion app - a call companion app is one which provides no user interface itself,
- *     but exposes call information to another display surface, such as a wearable device.  The
- *     user may choose multiple apps to fill this role.</li>
- * </ol>
- * <p>
- * Apps which wish to fulfill one of the above roles use the {@link android.app.role.RoleManager}
- * to request that they fill the desired role.
- *
  * <h2>Becoming the Default Phone App</h2>
+ * The default dialer/phone app is one which provides the in-call user interface while the device is
+ * in a call.  A device is bundled with a system provided default dialer/phone app.  The user may
+ * choose a single app to take over this role from the system app.  An app which wishes to fulfill
+ * one this role uses the {@code android.app.role.RoleManager} to request that they fill the role.
+ * <p>
  * An app filling the role of the default phone app provides a user interface while the device is in
  * a call, and the device is not in car mode.
  * <p>
@@ -193,47 +179,6 @@ import java.util.List;
  * notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, builder.build());
  * }</pre>
  * <p>
- * <h2>Becoming the Default Car-mode Phone App</h2>
- * An app filling the role of the default car-mode dialer/phone app provides a user interface while
- * the device is in a call, and in car mode.  See
- * {@link android.app.UiModeManager#ACTION_ENTER_CAR_MODE} for more information about car mode.
- * When the device is in car mode, Telecom binds to the default car-mode dialer/phone app instead
- * of the usual dialer/phone app.
- * <p>
- * Similar to the requirements for becoming the default dialer/phone app, your app must declare a
- * manifest entry for its {@link InCallService} implementation.  Your manifest entry should ensure
- * the following conditions are met:
- * <ul>
- *     <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_UI} metadata.</li>
- *     <li>Set the {@link TelecomManager#METADATA_IN_CALL_SERVICE_CAR_MODE_UI} metadata to
- *     {@code true}<li>
- *     <li>Your app must request the permission
- *     {@link android.Manifest.permission.CALL_COMPANION_APP}.</li>
- * </ul>
- * <p>
- * Your app should request to fill the role {@code android.app.role.CAR_MODE_DIALER} in order to
- * become the default (see <a href="#requestRole">above</a> for how to request your app fills this
- * role).
- *
- * <h2>Becoming a Call Companion App</h2>
- * An app which fills the companion app role does not directly provide a user interface while the
- * device is in a call.  Instead, it is typically used to relay information about calls to another
- * display surface, such as a wearable device.
- * <p>
- * Similar to the requirements for becoming the default dialer/phone app, your app must declare a
- * manifest entry for its {@link InCallService} implementation.  Your manifest entry should
- * ensure the following conditions are met:
- * <ul>
- *     <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_UI} metadata.</li>
- *     <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_CAR_MODE_UI}
- *     metadata.</li>
- *     <li>Your app must request the permission
- *     {@link android.Manifest.permission.CALL_COMPANION_APP}.</li>
- * </ul>
- * <p>
- * Your app should request to fill the role {@code android.app.role.CALL_COMPANION} in order to
- * become a call companion app (see <a href="#requestRole">above</a> for how to request your app
- * fills this role).
  */
 public abstract class InCallService extends Service {
 

telecomm/java/android/telecom/TelecomManager.java

@@ -16,7 +16,6 @@ package android.telecom;
 
 import android.Manifest;
 import android.annotation.IntDef;
-import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.annotation.RequiresPermission;
 import android.annotation.SuppressAutoDoc;
@@ -497,6 +496,9 @@ public class TelecomManager {
      * Dialer implementations (see {@link #getDefaultDialerPackage()}) which would also like to
      * override the system provided ringing should set this meta-data to {@code true} in the
      * manifest registration of their {@link InCallService}.
+     * <p>
+     * When {@code true}, it is the {@link InCallService}'s responsibility to play a ringtone for
+     * all incoming calls.
      */
     public static final String METADATA_IN_CALL_SERVICE_RINGING =
             "android.telecom.IN_CALL_SERVICE_RINGING";
@@ -1495,8 +1497,21 @@ public class TelecomManager {
 
     /**
      * Silences the ringer if a ringing call exists.
-     *
-     * Requires permission: {@link android.Manifest.permission#MODIFY_PHONE_STATE}
+     * <p>
+     * This method can only be relied upon to stop the ringtone for a call if the ringtone has
+     * already started playing.  It is intended to handle use-cases such as silencing a ringing call
+     * when the user presses the volume button during ringing.
+     * <p>
+     * If this method is called prior to when the ringtone begins playing, the ringtone will not be
+     * silenced.  As such it is not intended as a means to avoid playing of a ringtone.
+     * <p>
+     * A dialer app which wants to have more control over ringtone playing should declare
+     * {@link TelecomManager#METADATA_IN_CALL_SERVICE_RINGING} in the manifest entry for their
+     * {@link InCallService} implementation to indicate that the app wants to be responsible for
+     * playing the ringtone for all incoming calls.
+     * <p>
+     * Requires permission: {@link android.Manifest.permission#MODIFY_PHONE_STATE} or that the
+     * app fills the dialer role (see {@link #getDefaultDialerPackage()}).
      */
     @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE)
     public void silenceRinger() {