API tweaks in response to feedback
Update documentation on PhoneAccount#EXTRA_SORT_ORDER to make it more
clear what the sorting order is in edge cases.
Make DisconnectCause#REASON_EMULATING_SINGLE_CALL public, since it might
get propogated up to dialer apps.
Fixes: 169153499
Test: docs only
Change-Id: I7f810f909a8a61b422283c3bafcc97307e4d863b
diff --git a/telecomm/java/android/telecom/PhoneAccount.java b/telecomm/java/android/telecom/PhoneAccount.java
index c20e5ad..4a3561b 100644
--- a/telecomm/java/android/telecom/PhoneAccount.java
+++ b/telecomm/java/android/telecom/PhoneAccount.java
@@ -28,6 +28,7 @@
import android.os.Bundle;
import android.os.Parcel;
import android.os.Parcelable;
+import android.telephony.TelephonyManager;
import android.text.TextUtils;
import java.util.ArrayList;
@@ -52,8 +53,17 @@
*
* This is an extras key set via {@link Builder#setExtras} which determines the order in which
* {@link PhoneAccount}s from the same {@link ConnectionService} are sorted. The accounts
- * are sorted by this key via standard lexicographical order, and this ordering is used to
+ * are sorted by this key via standard lexicographical order, (as implemented in
+ * {@link String#compareTo}), and this ordering is used to
* determine priority when a call can be placed via multiple accounts.
+ *
+ * When multiple {@link PhoneAccount}s are supplied with the same sort order key, no ordering is
+ * guaranteed between those {@link PhoneAccount}s. Additionally, no ordering is guaranteed
+ * between {@link PhoneAccount}s that do not supply this extra, and all such accounts
+ * will be sorted after the accounts that do supply this extra.
+ *
+ * An example of a sort order key is slot index (see {@link TelephonyManager#getSlotIndex()}),
+ * which is the one used by the cell Telephony stack.
* @hide
*/
@SystemApi