Update javadocs for API review

Move plan requirements from Builder to SubscriptionPlan
Null and empty network types do not have the same behavior.
Clarify where plan requirements is enforced

Bug: 143550313
Test: none

Change-Id: I80c3b4425f317d5b4e9c685878c866742b706b85
Merged-In: I80c3b4425f317d5b4e9c685878c866742b706b85

2 files changed, 13 insertions, 14 deletions

diff --git a/core/java/android/telephony/SubscriptionPlan.java b/core/java/android/telephony/SubscriptionPlan.java
index e24eb2696c6c..28a5c2086ede 100644
--- a/core/java/android/telephony/SubscriptionPlan.java
+++ b/core/java/android/telephony/SubscriptionPlan.java
@@ -44,6 +44,14 @@ import java.util.Objects;
  * as explaining how much mobile data they have remaining, and what will happen
  * when they run out.
  *
+ * If specifying network types, the developer must supply at least one plan
+ * that applies to all network types (default), and all additional plans
+ * may not include a particular network type more than once.
+ * This is enforced by {@link SubscriptionManager} when setting the plans.
+ *
+ * Plan selection will prefer plans that have specific network types defined
+ * over plans that apply to all network types.
+ *
  * @see SubscriptionManager#setSubscriptionPlans(int, java.util.List)
  * @see SubscriptionManager#getSubscriptionPlans(int)
  */
@@ -213,7 +221,7 @@ public final class SubscriptionPlan implements Parcelable {
 
     /**
      * Return an array containing all {@link NetworkType}s this SubscriptionPlan applies to.
-     * A null array means this SubscriptionPlan applies to all network types.
+     * A null value means this SubscriptionPlan applies to all network types.
      */
     public @Nullable @NetworkType int[] getNetworkTypes() {
         return networkTypes;
@@ -372,20 +380,13 @@ public final class SubscriptionPlan implements Parcelable {
 
         /**
          * Set the network types this SubscriptionPlan applies to.
-         * The developer must supply at least one plan that applies to all network types (default),
-         * and all additional plans may not include a particular network type more than once.
-         * Plan selection will prefer plans that have specific network types defined
-         * over plans that apply to all network types.
          *
          * @param networkTypes a set of all {@link NetworkType}s that apply to this plan.
-         *            A null value or empty array means the plan applies to all network types.
+         *            A null value means the plan applies to all network types,
+         *            and an empty array means the plan applies to no network types.
          */
         public @NonNull Builder setNetworkTypes(@Nullable @NetworkType int[] networkTypes) {
-            if (networkTypes == null || networkTypes.length == 0) {
-                plan.networkTypes = null;
-            } else {
-                plan.networkTypes = networkTypes;
-            }
+            plan.networkTypes = networkTypes;
             return this;
         }
     }
diff --git a/telephony/java/android/telephony/SubscriptionManager.java b/telephony/java/android/telephony/SubscriptionManager.java
index 9d744a61db68..4de9e1e4c1c7 100644
--- a/telephony/java/android/telephony/SubscriptionManager.java
+++ b/telephony/java/android/telephony/SubscriptionManager.java
@@ -2500,12 +2500,10 @@ public class SubscriptionManager {
      * @param plans the list of plans. The first plan is always the primary and
      *            most important plan. Any additional plans are secondary and
      *            may not be displayed or used by decision making logic.
-     *            The list of all plans must meet the requirements defined in
-     *            {@link SubscriptionPlan.Builder#setNetworkTypes(int[])}.
      * @throws SecurityException if the caller doesn't meet the requirements
      *             outlined above.
      * @throws IllegalArgumentException if plans don't meet the requirements
-     *             mentioned above.
+     *             defined in {@link SubscriptionPlan}.
      */
     public void setSubscriptionPlans(int subId, @NonNull List<SubscriptionPlan> plans) {
         try {