Merge "Clarify AGC fields" into main

2 files changed, 12 insertions, 0 deletions

diff --git a/location/java/android/location/GnssMeasurement.java b/location/java/android/location/GnssMeasurement.java
index 200d4ef86146..6ae73a2e6fe5 100644
--- a/location/java/android/location/GnssMeasurement.java
+++ b/location/java/android/location/GnssMeasurement.java
@@ -1484,6 +1484,10 @@ public final class GnssMeasurement implements Parcelable {
      * in an open sky test - the important aspect of this output is that changes in this value are
      * indicative of changes on input signal power in the frequency band for this measurement.
      *
+     * <p> This field is part of the GnssMeasurement object so it is only reported when the GNSS
+     * measurement is reported. E.g., when a GNSS signal is too weak to be acquired, the AGC value
+     * is not reported.
+     *
      * <p> The value is only available if {@link #hasAutomaticGainControlLevelDb()} is {@code true}
      *
      * @deprecated Use {@link GnssMeasurementsEvent#getGnssAutomaticGainControls()} instead.
diff --git a/location/java/android/location/GnssMeasurementsEvent.java b/location/java/android/location/GnssMeasurementsEvent.java
index 4fc2ee8b7fb0..8cdfd013130a 100644
--- a/location/java/android/location/GnssMeasurementsEvent.java
+++ b/location/java/android/location/GnssMeasurementsEvent.java
@@ -158,6 +158,14 @@ public final class GnssMeasurementsEvent implements Parcelable {
     /**
      * Gets the collection of {@link GnssAutomaticGainControl} associated with the
      * current event.
+     *
+     * <p>This field must be reported when the GNSS measurement engine is running, even when the
+     * GnssMeasurement or GnssClock fields are not reported yet. E.g., when a GNSS signal is too
+     * weak to be acquired, the AGC value must still be reported.
+     *
+     * <p>For devices that do not support this field, an empty collection is returned. In that case,
+     * please use {@link GnssMeasurement#hasAutomaticGainControlLevelDb()}
+     * and {@link GnssMeasuremen#getAutomaticGainControlLevelDb()}.
      */
     @NonNull
     public Collection<GnssAutomaticGainControl> getGnssAutomaticGainControls() {