From bace6e3132569f8c4ac246232a1a9354913255f6 Mon Sep 17 00:00:00 2001
From: Nathan Harold <nharold@google.com>
Date: Tue, 26 Jun 2018 16:55:54 -0700
Subject: [PATCH] Update Docstrings for CellSignalStrengthLte

Add comments to the docstrings to indicate optional
values that may not always be reported. Users are
still reporting bugs for missing fields, which we
consider optional. This should clarify which methods
are optional vs mandatory for LTE.

For signal strength, RSRP is mandatory, and TA is
mandatory while in LTE_ACTIVE. RSSNR, RSRQ, and CQI
are all optional.

Bug: 36995487
Test: compilation (docstring-only change)
Change-Id: I05af5d42cbf6836109efe6441e95223e81671534
---
 .../telephony/CellSignalStrengthLte.java        | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/telephony/java/android/telephony/CellSignalStrengthLte.java b/telephony/java/android/telephony/CellSignalStrengthLte.java
index 7e86966e2c1be..2b6928e2e4f15 100644
--- a/telephony/java/android/telephony/CellSignalStrengthLte.java
+++ b/telephony/java/android/telephony/CellSignalStrengthLte.java
@@ -121,6 +121,8 @@ public final class CellSignalStrengthLte extends CellSignalStrength implements P
 
     /**
      * Get reference signal received quality
+     *
+     * @return the RSRQ if available or Integer.MAX_VALUE if unavailable.
      */
     public int getRsrq() {
         return mRsrq;
@@ -128,13 +130,17 @@ public final class CellSignalStrengthLte extends CellSignalStrength implements P
 
     /**
      * Get reference signal signal-to-noise ratio
+     *
+     * @return the RSSNR if available or Integer.MAX_VALUE if unavailable.
      */
     public int getRssnr() {
         return mRssnr;
     }
 
     /**
-     * Get reference signal received power
+     * Get reference signal received power in dBm
+     *
+     * @return the RSRP of the measured cell.
      */
     public int getRsrp() {
         return mRsrp;
@@ -142,13 +148,17 @@ public final class CellSignalStrengthLte extends CellSignalStrength implements P
 
     /**
      * Get channel quality indicator
+     *
+     * @return the CQI if available or Integer.MAX_VALUE if unavailable.
      */
     public int getCqi() {
         return mCqi;
     }
 
     /**
-     * Get signal strength as dBm
+     * Get signal strength in dBm
+     *
+     * @return the RSRP of the measured cell.
      */
     @Override
     public int getDbm() {
@@ -175,7 +185,8 @@ public final class CellSignalStrengthLte extends CellSignalStrength implements P
      * Get the timing advance value for LTE, as a value in range of 0..1282.
      * Integer.MAX_VALUE is reported when there is no active RRC
      * connection. Refer to 3GPP 36.213 Sec 4.2.3
-     * @return the LTE timing advance, if available.
+     *
+     * @return the LTE timing advance if available or Integer.MAX_VALUE if unavailable.
      */
     public int getTimingAdvance() {
         return mTimingAdvance;