Merge "Update Javadocs for CellInfo Classes"

am: a49f1b725f

Change-Id: Ib49e00661155178b6303f88258128cdb3d1a8691

api/current.txt

@@ -42310,9 +42310,9 @@ package android.telephony {
     method public int getCid();
     method public int getLac();
     method @Deprecated public int getMcc();
-    method public String getMccString();
+    method @Nullable public String getMccString();
     method @Deprecated public int getMnc();
-    method public String getMncString();
+    method @Nullable public String getMncString();
     method @Nullable public String getMobileNetworkOperator();
     method @Deprecated public int getPsc();
     method public void writeToParcel(android.os.Parcel, int);
@@ -42324,9 +42324,9 @@ package android.telephony {
     method public int getCi();
     method public int getEarfcn();
     method @Deprecated public int getMcc();
-    method public String getMccString();
+    method @Nullable public String getMccString();
     method @Deprecated public int getMnc();
-    method public String getMncString();
+    method @Nullable public String getMncString();
     method @Nullable public String getMobileNetworkOperator();
     method public int getPci();
     method public int getTac();
@@ -42349,8 +42349,8 @@ package android.telephony {
     method public int getCid();
     method public int getCpid();
     method public int getLac();
-    method public String getMccString();
+    method @Nullable public String getMccString();
-    method public String getMncString();
+    method @Nullable public String getMncString();
     method @Nullable public String getMobileNetworkOperator();
     method public int getUarfcn();
     method public void writeToParcel(android.os.Parcel, int);
@@ -42361,9 +42361,9 @@ package android.telephony {
     method public int getCid();
     method public int getLac();
     method @Deprecated public int getMcc();
-    method public String getMccString();
+    method @Nullable public String getMccString();
     method @Deprecated public int getMnc();
-    method public String getMncString();
+    method @Nullable public String getMncString();
     method @Nullable public String getMobileNetworkOperator();
     method public int getPsc();
     method public int getUarfcn();
@@ -42386,22 +42386,22 @@ package android.telephony {
   }
 
   public final class CellInfoCdma extends android.telephony.CellInfo implements android.os.Parcelable {
-    method public android.telephony.CellIdentityCdma getCellIdentity();
+    method @NonNull public android.telephony.CellIdentityCdma getCellIdentity();
-    method public android.telephony.CellSignalStrengthCdma getCellSignalStrength();
+    method @NonNull public android.telephony.CellSignalStrengthCdma getCellSignalStrength();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final android.os.Parcelable.Creator<android.telephony.CellInfoCdma> CREATOR;
   }
 
   public final class CellInfoGsm extends android.telephony.CellInfo implements android.os.Parcelable {
-    method public android.telephony.CellIdentityGsm getCellIdentity();
+    method @NonNull public android.telephony.CellIdentityGsm getCellIdentity();
-    method public android.telephony.CellSignalStrengthGsm getCellSignalStrength();
+    method @NonNull public android.telephony.CellSignalStrengthGsm getCellSignalStrength();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final android.os.Parcelable.Creator<android.telephony.CellInfoGsm> CREATOR;
   }
 
   public final class CellInfoLte extends android.telephony.CellInfo implements android.os.Parcelable {
-    method public android.telephony.CellIdentityLte getCellIdentity();
+    method @NonNull public android.telephony.CellIdentityLte getCellIdentity();
-    method public android.telephony.CellSignalStrengthLte getCellSignalStrength();
+    method @NonNull public android.telephony.CellSignalStrengthLte getCellSignalStrength();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final android.os.Parcelable.Creator<android.telephony.CellInfoLte> CREATOR;
   }
@@ -42437,7 +42437,7 @@ package android.telephony {
     method public abstract boolean equals(Object);
     method public abstract int getAsuLevel();
     method public abstract int getDbm();
-    method public abstract int getLevel();
+    method @IntRange(from=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_GREAT) public abstract int getLevel();
     method public abstract int hashCode();
     field public static final int SIGNAL_STRENGTH_GOOD = 3; // 0x3
     field public static final int SIGNAL_STRENGTH_GREAT = 4; // 0x4
@@ -42457,7 +42457,7 @@ package android.telephony {
     method public int getEvdoEcio();
     method public int getEvdoLevel();
     method public int getEvdoSnr();
-    method public int getLevel();
+    method @IntRange(from=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_GREAT) public int getLevel();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final android.os.Parcelable.Creator<android.telephony.CellSignalStrengthCdma> CREATOR;
   }
@@ -42467,7 +42467,7 @@ package android.telephony {
     method public int getAsuLevel();
     method public int getBitErrorRate();
     method public int getDbm();
-    method public int getLevel();
+    method @IntRange(from=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_GREAT) public int getLevel();
     method public int getTimingAdvance();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final android.os.Parcelable.Creator<android.telephony.CellSignalStrengthGsm> CREATOR;
@@ -42478,7 +42478,7 @@ package android.telephony {
     method public int getAsuLevel();
     method public int getCqi();
     method public int getDbm();
-    method public int getLevel();
+    method @IntRange(from=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_GREAT) public int getLevel();
     method public int getRsrp();
     method public int getRsrq();
     method public int getRssi();
@@ -42495,7 +42495,7 @@ package android.telephony {
     method public int getCsiRsrq();
     method public int getCsiSinr();
     method public int getDbm();
-    method public int getLevel();
+    method @IntRange(from=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_GREAT) public int getLevel();
     method public int getSsRsrp();
     method public int getSsRsrq();
     method public int getSsSinr();
@@ -42507,7 +42507,7 @@ package android.telephony {
     method public int describeContents();
     method public int getAsuLevel();
     method public int getDbm();
-    method public int getLevel();
+    method @IntRange(from=0, to=4) public int getLevel();
     method public int getRscp();
     method public void writeToParcel(android.os.Parcel, int);
     field @NonNull public static final android.os.Parcelable.Creator<android.telephony.CellSignalStrengthTdscdma> CREATOR;
@@ -42517,7 +42517,7 @@ package android.telephony {
     method public int describeContents();
     method public int getAsuLevel();
     method public int getDbm();
-    method public int getLevel();
+    method @IntRange(from=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to=android.telephony.CellSignalStrength.SIGNAL_STRENGTH_GREAT) public int getLevel();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final android.os.Parcelable.Creator<android.telephony.CellSignalStrengthWcdma> CREATOR;
   }

telephony/java/android/telephony/CellIdentityGsm.java

@@ -166,6 +166,7 @@ public final class CellIdentityGsm extends CellIdentity {
     /**
      * @return Mobile Country Code in string format, null if unavailable.
      */
+    @Nullable
     public String getMccString() {
         return mMccStr;
     }
@@ -173,6 +174,7 @@ public final class CellIdentityGsm extends CellIdentity {
     /**
      * @return Mobile Network Code in string format, null if unavailable.
      */
+    @Nullable
     public String getMncString() {
         return mMncStr;
     }

telephony/java/android/telephony/CellIdentityLte.java

@@ -187,6 +187,7 @@ public final class CellIdentityLte extends CellIdentity {
     /**
      * @return Mobile Country Code in string format, null if unavailable.
      */
+    @Nullable
     public String getMccString() {
         return mMccStr;
     }
@@ -194,6 +195,7 @@ public final class CellIdentityLte extends CellIdentity {
     /**
      * @return Mobile Network Code in string format, null if unavailable.
      */
+    @Nullable
     public String getMncString() {
         return mMncStr;
     }

telephony/java/android/telephony/CellIdentityTdscdma.java

@@ -104,6 +104,7 @@ public final class CellIdentityTdscdma extends CellIdentity {
      * Get Mobile Country Code in string format
      * @return Mobile Country Code in string format, null if unknown
      */
+    @Nullable
     public String getMccString() {
         return mMccStr;
     }
@@ -112,6 +113,7 @@ public final class CellIdentityTdscdma extends CellIdentity {
      * Get Mobile Network Code in string format
      * @return Mobile Network Code in string format, null if unknown
      */
+    @Nullable
     public String getMncString() {
         return mMncStr;
     }

telephony/java/android/telephony/CellIdentityWcdma.java

@@ -150,6 +150,7 @@ public final class CellIdentityWcdma extends CellIdentity {
     /**
      * @return Mobile Country Code in string version, null if unavailable.
      */
+    @Nullable
     public String getMccString() {
         return mMccStr;
     }
@@ -157,6 +158,7 @@ public final class CellIdentityWcdma extends CellIdentity {
     /**
      * @return Mobile Network Code in string version, null if unavailable.
      */
+    @Nullable
     public String getMncString() {
         return mMncStr;
     }

telephony/java/android/telephony/CellInfoCdma.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.NonNull;
 import android.annotation.UnsupportedAppUsage;
 import android.os.Build;
 import android.os.Parcel;
@@ -76,18 +77,25 @@ public final class CellInfoCdma extends CellInfo implements Parcelable {
                 new CellSignalStrengthCdma(cic.signalStrengthCdma, cic.signalStrengthEvdo);
     }
 
+    /**
+     * @return a {@link CellIdentityCdma} instance.
+     */
     @Override
-    public CellIdentityCdma getCellIdentity() {
+    public @NonNull CellIdentityCdma getCellIdentity() {
         return mCellIdentityCdma;
     }
+
     /** @hide */
     @UnsupportedAppUsage
     public void setCellIdentity(CellIdentityCdma cid) {
         mCellIdentityCdma = cid;
     }
 
+    /**
+     * @return a {@link CellSignalStrengthCdma} instance.
+     */
     @Override
-    public CellSignalStrengthCdma getCellSignalStrength() {
+    public @NonNull CellSignalStrengthCdma getCellSignalStrength() {
         return mCellSignalStrengthCdma;
     }
 

telephony/java/android/telephony/CellInfoGsm.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.NonNull;
 import android.annotation.UnsupportedAppUsage;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -71,17 +72,24 @@ public final class CellInfoGsm extends CellInfo implements Parcelable {
         mCellSignalStrengthGsm = new CellSignalStrengthGsm(cig.signalStrengthGsm);
     }
 
+    /**
+     * @return a {@link CellIdentityGsm} instance.
+     */
     @Override
-    public CellIdentityGsm getCellIdentity() {
+    public @NonNull CellIdentityGsm getCellIdentity() {
         return mCellIdentityGsm;
     }
+
     /** @hide */
     public void setCellIdentity(CellIdentityGsm cid) {
         mCellIdentityGsm = cid;
     }
 
+    /**
+     * @return a {@link CellSignalStrengthGsm} instance.
+     */
     @Override
-    public CellSignalStrengthGsm getCellSignalStrength() {
+    public @NonNull CellSignalStrengthGsm getCellSignalStrength() {
         return mCellSignalStrengthGsm;
     }
 

telephony/java/android/telephony/CellInfoLte.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.NonNull;
 import android.annotation.UnsupportedAppUsage;
 import android.os.Build;
 import android.os.Parcel;
@@ -79,11 +80,15 @@ public final class CellInfoLte extends CellInfo implements Parcelable {
         mCellConfig = new CellConfigLte(cil.cellConfig);
     }
 
+    /**
+     * @return a {@link CellIdentityLte} instance.
+     */
     @Override
-    public CellIdentityLte getCellIdentity() {
+    public @NonNull CellIdentityLte getCellIdentity() {
         if (DBG) log("getCellIdentity: " + mCellIdentityLte);
         return mCellIdentityLte;
     }
+
     /** @hide */
     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023)
     public void setCellIdentity(CellIdentityLte cid) {
@@ -91,8 +96,11 @@ public final class CellInfoLte extends CellInfo implements Parcelable {
         mCellIdentityLte = cid;
     }
 
+    /**
+     * @return a {@link CellSignalStrengthLte} instance.
+     */
     @Override
-    public CellSignalStrengthLte getCellSignalStrength() {
+    public @NonNull CellSignalStrengthLte getCellSignalStrength() {
         if (DBG) log("getCellSignalStrength: " + mCellSignalStrengthLte);
         return mCellSignalStrengthLte;
     }

telephony/java/android/telephony/CellInfoNr.java

@@ -43,12 +43,18 @@ public final class CellInfoNr extends CellInfo {
         mCellSignalStrength = other.mCellSignalStrength;
     }
 
+    /**
+     * @return a {@link CellIdentityNr} instance.
+     */
     @Override
     @NonNull
     public CellIdentity getCellIdentity() {
         return mCellIdentity;
     }
 
+    /**
+     * @return a {@link CellSignalStrengthNr} instance.
+     */
     @Override
     @NonNull
     public CellSignalStrength getCellSignalStrength() {

telephony/java/android/telephony/CellInfoTdscdma.java

@@ -75,6 +75,9 @@ public final class CellInfoTdscdma extends CellInfo implements Parcelable {
         mCellSignalStrengthTdscdma = new CellSignalStrengthTdscdma(cit.signalStrengthTdscdma);
     }
 
+    /**
+     * @return a {@link CellIdentityTdscdma} instance.
+     */
     @Override
     public @NonNull CellIdentityTdscdma getCellIdentity() {
         return mCellIdentityTdscdma;
@@ -85,6 +88,9 @@ public final class CellInfoTdscdma extends CellInfo implements Parcelable {
         mCellIdentityTdscdma = cid;
     }
 
+    /**
+     * @return a {@link CellSignalStrengthTdscdma} instance.
+     */
     @Override
     public @NonNull CellSignalStrengthTdscdma getCellSignalStrength() {
         return mCellSignalStrengthTdscdma;

telephony/java/android/telephony/CellInfoWcdma.java

@@ -71,15 +71,22 @@ public final class CellInfoWcdma extends CellInfo implements Parcelable {
         mCellSignalStrengthWcdma = new CellSignalStrengthWcdma(ciw.signalStrengthWcdma);
     }
 
+    /**
+     * @return a {@link CellIdentityWcdma} instance.
+     */
     @Override
     public CellIdentityWcdma getCellIdentity() {
         return mCellIdentityWcdma;
     }
+
     /** @hide */
     public void setCellIdentity(CellIdentityWcdma cid) {
         mCellIdentityWcdma = cid;
     }
 
+    /**
+     * @return a {@link CellSignalStrengthWcdma} instance.
+     */
     @Override
     public CellSignalStrengthWcdma getCellSignalStrength() {
         return mCellSignalStrengthWcdma;

telephony/java/android/telephony/CellSignalStrength.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.IntRange;
 import android.os.PersistableBundle;
 
 /**
@@ -57,23 +58,24 @@ public abstract class CellSignalStrength {
     public abstract void setDefaultValues();
 
     /**
-     * Get signal level as an int from 0..4
+     * Retrieve an abstract level value for the overall signal quality.
-     * <p>
+     *
-     * @see SIGNAL_STRENGTH_NONE_OR_UNKNOWN
+     * @return a single integer from 0 to 4 representing the general signal quality.
-     * @see SIGNAL_STRENGTH_POOR
+     *     0 represents very poor or unknown signal quality while 4 represents excellent
-     * @see SIGNAL_STRENGTH_MODERATE
+     *     signal quality.
-     * @see SIGNAL_STRENGTH_GOOD
-     * @see SIGNAL_STRENGTH_GREAT
      */
+    @IntRange(from = SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to = SIGNAL_STRENGTH_GREAT)
     public abstract int getLevel();
 
     /**
-     * Get the signal level as an asu value between 0..31, 99 is unknown
+     * Get the technology-specific signal strength in Arbitrary Strength Units, calculated from the
+     * strength of the pilot signal or equivalent.
      */
     public abstract int getAsuLevel();
 
     /**
-     * Get the signal strength as dBm
+     * Get the technology-specific signal strength in dBm, which is the signal strength of the
+     * pilot signal or equivalent.
      */
     public abstract int getDbm();
 

telephony/java/android/telephony/CellSignalStrengthCdma.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.IntRange;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.os.PersistableBundle;
@@ -114,13 +115,9 @@ public final class CellSignalStrengthCdma extends CellSignalStrength implements
         mLevel = SIGNAL_STRENGTH_NONE_OR_UNKNOWN;
     }
 
-    /**
+    /** {@inheritDoc} */
-     * Retrieve an abstract level value for the overall signal strength.
-     *
-     * @return a single integer from 0 to 4 representing the general signal quality.
-     *     0 represents very poor signal strength while 4 represents a very strong signal strength.
-     */
     @Override
+    @IntRange(from = SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to = SIGNAL_STRENGTH_GREAT)
     public int getLevel() {
         return mLevel;
     }

telephony/java/android/telephony/CellSignalStrengthGsm.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.IntRange;
 import android.annotation.UnsupportedAppUsage;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -97,13 +98,9 @@ public final class CellSignalStrengthGsm extends CellSignalStrength implements P
         mLevel = SIGNAL_STRENGTH_NONE_OR_UNKNOWN;
     }
 
-    /**
+    /** {@inheritDoc} */
-     * Retrieve an abstract level value for the overall signal strength.
-     *
-     * @return a single integer from 0 to 4 representing the general signal quality.
-     *     0 represents very poor signal strength while 4 represents a very strong signal strength.
-     */
     @Override
+    @IntRange(from = SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to = SIGNAL_STRENGTH_GREAT)
     public int getLevel() {
         return mLevel;
     }
@@ -141,7 +138,7 @@ public final class CellSignalStrengthGsm extends CellSignalStrength implements P
     /**
      * Get the RSSI in ASU.
      *
-     * Asu is calculated based on 3GPP RSRP. Refer to 3GPP 27.007 (Ver 10.3.0) Sec 8.69
+     * Asu is calculated based on 3GPP RSSI. Refer to 3GPP 27.007 (Ver 10.3.0) Sec 8.69
      *
      * @return RSSI in ASU 0..31, 99, or UNAVAILABLE
      */

telephony/java/android/telephony/CellSignalStrengthLte.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.IntRange;
 import android.annotation.UnsupportedAppUsage;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -145,13 +146,9 @@ public final class CellSignalStrengthLte extends CellSignalStrength implements P
         mLevel = SIGNAL_STRENGTH_NONE_OR_UNKNOWN;
     }
 
-    /**
+    /** {@inheritDoc} */
-     * Retrieve an abstract level value for the overall signal strength.
-     *
-     * @return a single integer from 0 to 4 representing the general signal quality.
-     *     0 represents very poor signal strength while 4 represents a very strong signal strength.
-     */
     @Override
+    @IntRange(from = SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to = SIGNAL_STRENGTH_GREAT)
     public int getLevel() {
         return mLevel;
     }

telephony/java/android/telephony/CellSignalStrengthNr.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.IntRange;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.os.PersistableBundle;
@@ -183,7 +184,9 @@ public final class CellSignalStrengthNr extends CellSignalStrength implements Pa
         mLevel = SIGNAL_STRENGTH_NONE_OR_UNKNOWN;
     }
 
+    /** {@inheritDoc} */
     @Override
+    @IntRange(from = SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to = SIGNAL_STRENGTH_GREAT)
     public int getLevel() {
         return mLevel;
     }
@@ -227,6 +230,9 @@ public final class CellSignalStrengthNr extends CellSignalStrength implements Pa
         return asuLevel;
     }
 
+    /**
+     * Get the CSI-RSRP as dBm value -140..-44dBm or {@link CellInfo#UNAVAILABLE UNAVAILABLE}.
+     */
     @Override
     public int getDbm() {
         return mCsiRsrp;

telephony/java/android/telephony/CellSignalStrengthTdscdma.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -121,13 +122,10 @@ public final class CellSignalStrengthTdscdma extends CellSignalStrength implemen
         mLevel = SIGNAL_STRENGTH_NONE_OR_UNKNOWN;
     }
 
-    /**
+
-     * Retrieve an abstract level value for the overall signal strength.
+    /** {@inheritDoc} */
-     *
-     * @return a single integer from 0 to 4 representing the general signal quality.
-     *     0 represents very poor signal strength while 4 represents a very strong signal strength.
-     */
     @Override
+    @IntRange(from = 0, to = 4)
     public int getLevel() {
         return mLevel;
     }
@@ -144,7 +142,7 @@ public final class CellSignalStrengthTdscdma extends CellSignalStrength implemen
     }
 
     /**
-     * Get the signal strength as dBm
+     * Get the RSCP as dBm value -120..-24dBm or {@link CellInfo#UNAVAILABLE UNAVAILABLE}.
      */
     @Override
     public int getDbm() {

telephony/java/android/telephony/CellSignalStrengthWcdma.java

@@ -16,6 +16,7 @@
 
 package android.telephony;
 
+import android.annotation.IntRange;
 import android.annotation.StringDef;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -143,13 +144,9 @@ public final class CellSignalStrengthWcdma extends CellSignalStrength implements
         mLevel = SIGNAL_STRENGTH_NONE_OR_UNKNOWN;
     }
 
-    /**
+    /** {@inheritDoc} */
-     * Retrieve an abstract level value for the overall signal strength.
-     *
-     * @return a single integer from 0 to 4 representing the general signal quality.
-     *     0 represents very poor signal strength while 4 represents a very strong signal strength.
-     */
     @Override
+    @IntRange(from = SIGNAL_STRENGTH_NONE_OR_UNKNOWN, to = SIGNAL_STRENGTH_GREAT)
     public int getLevel() {
         return mLevel;
     }
@@ -202,7 +199,7 @@ public final class CellSignalStrengthWcdma extends CellSignalStrength implements
     }
 
     /**
-     * Get the signal strength as dBm
+     * Get the RSCP as dBm value -120..-24dBm or {@link CellInfo#UNAVAILABLE UNAVAILABLE}.
      */
     @Override
     public int getDbm() {