Clarifiy ADR states in documentation

Bug: 167930284
Test: n/a
Change-Id: Ifa0633b2cfa7bb80e32d2c68d70992bc1b0c5461
diff --git a/current.txt b/current.txt
index c9a923e..fc0cc07 100644
--- a/current.txt
+++ b/current.txt
@@ -767,6 +767,8 @@
 98592d193a717066facf91428426e5abe211e3bd718bc372e29fb944ddbe6e7c android.hardware.wifi.supplicant@1.3::types
 
 # ABI preserving changes to HALs during Android S
+1ca372cd67d197df099e87616a613ba6ede6552638a603e18f86c8834302c3d1 android.hardware.gnss@1.0::IGnssMeasurementCallback
+6a271e493907e8ba20912e42771bd0d99ae45431a851d5675ef9496d02510a34 android.hardware.gnss@1.1::IGnssMeasurementCallback
 3da3ce039247872d95c6bd48621dbfdfa1c2d2a91a90f257862f87ee2bc46300 android.hardware.health@2.1::types
 cd84ab19c590e0e73dd2307b591a3093ee18147ef95e6d5418644463a6620076 android.hardware.neuralnetworks@1.2::IDevice
 9625e85f56515ad2cf87b6a1847906db669f746ea4ab02cd3d4ca25abc9b0109 android.hardware.neuralnetworks@1.2::types
diff --git a/gnss/1.0/IGnssMeasurementCallback.hal b/gnss/1.0/IGnssMeasurementCallback.hal
index 2d44766..d219af0 100644
--- a/gnss/1.0/IGnssMeasurementCallback.hal
+++ b/gnss/1.0/IGnssMeasurementCallback.hal
@@ -106,8 +106,63 @@
         STATE_GLO_TOD_KNOWN          = 1 << 15,
     };
 
-    /**
+     /**
      * Flags indicating the Accumulated Delta Range's states.
+     *
+     * See the table below for a detailed interpretation of each state.
+     *
+     * +---------------------+-------------------+-----------------------------+
+     * | ADR_STATE           | Time of relevance | Interpretation              |
+     * +---------------------+-------------------+-----------------------------+
+     * | UNKNOWN             | ADR(t)            | No valid carrier phase      |
+     * |                     |                   | information is available    |
+     * |                     |                   | at time t.                  |
+     * +---------------------+-------------------+-----------------------------+
+     * | VALID               | ADR(t)            | Valid carrier phase         |
+     * |                     |                   | information is available    |
+     * |                     |                   | at time t. This indicates   |
+     * |                     |                   | that this measurement can   |
+     * |                     |                   | be used as a reference for  |
+     * |                     |                   | future measurements.        |
+     * |                     |                   | However, to compare it to   |
+     * |                     |                   | previous measurements to    |
+     * |                     |                   | compute delta range,        |
+     * |                     |                   | other bits should be        |
+     * |                     |                   | checked. Specifically, it   |
+     * |                     |                   | can be used for delta range |
+     * |                     |                   | computation if it is valid  |
+     * |                     |                   | and has no reset or cycle   |
+     * |                     |                   | slip at this epoch i.e.     |
+     * |                     |                   | if VALID_BIT == 1 &&        |
+     * |                     |                   | CYCLE_SLIP_BIT == 0 &&      |
+     * |                     |                   | RESET_BIT == 0.             |
+     * +---------------------+-------------------+-----------------------------+
+     * | RESET               | ADR(t) - ADR(t-1) | Carrier phase accumulation  |
+     * |                     |                   | has been restarted between  |
+     * |                     |                   | current time t and previous |
+     * |                     |                   | time t-1. This indicates    |
+     * |                     |                   | that this measurement can   |
+     * |                     |                   | be used as a reference for  |
+     * |                     |                   | future measurements, but it |
+     * |                     |                   | should not be compared to   |
+     * |                     |                   | previous measurements to    |
+     * |                     |                   | compute delta range.        |
+     * +---------------------+-------------------+-----------------------------+
+     * | CYCLE_SLIP          | ADR(t) - ADR(t-1) | Cycle slip(s) have been     |
+     * |                     |                   | detected between the        |
+     * |                     |                   | current time t and previous |
+     * |                     |                   | time t-1. This indicates    |
+     * |                     |                   | that this measurement can   |
+     * |                     |                   | be used as a reference for  |
+     * |                     |                   | future measurements.        |
+     * |                     |                   | Clients can use a           |
+     * |                     |                   | measurement with a cycle    |
+     * |                     |                   | slip to compute delta range |
+     * |                     |                   | against previous            |
+     * |                     |                   | measurements at their own   |
+     * |                     |                   | risk.                       |
+     * +---------------------+-------------------+-----------------------------+
+     *
      */
     @export(name="", value_prefix="GNSS_")
     enum GnssAccumulatedDeltaRangeState : uint16_t {
diff --git a/gnss/1.1/IGnssMeasurementCallback.hal b/gnss/1.1/IGnssMeasurementCallback.hal
index 5a60a56..36841ee 100644
--- a/gnss/1.1/IGnssMeasurementCallback.hal
+++ b/gnss/1.1/IGnssMeasurementCallback.hal
@@ -20,8 +20,18 @@
 
 /** The callback interface to report measurements from the HAL. */
 interface IGnssMeasurementCallback extends @1.0::IGnssMeasurementCallback {
-    /**
+     /**
      * Flags indicating the Accumulated Delta Range's states.
+     *
+     * See the table below for a detailed interpretation of each state. This is
+     * a continuation of the table from 1.1/IGnssMeasurementCallback.hal.
+     *
+     * +---------------------+-------------------+-----------------------------+
+     * | ADR_STATE           | Time of relevance | Interpretation              |
+     * +---------------------+-------------------+-----------------------------+
+     * | HALF_CYCLE_RESOLVED | ADR(t)            | Half cycle ambiguity is     |
+     * |                     |                   | resolved at time t.         |
+     * +---------------------+-------------------+-----------------------------+
      */
     enum GnssAccumulatedDeltaRangeState
             : @1.0::IGnssMeasurementCallback.GnssAccumulatedDeltaRangeState {