Merge "API docs tidy up"

5 files changed, 145 insertions, 99 deletions

diff --git a/core/java/android/app/timedetector/ManualTimeSuggestion.java b/core/java/android/app/timedetector/ManualTimeSuggestion.java
index 50de73855511..da51ce2a6aff 100644
--- a/core/java/android/app/timedetector/ManualTimeSuggestion.java
+++ b/core/java/android/app/timedetector/ManualTimeSuggestion.java
@@ -29,10 +29,18 @@ import java.util.List;
 import java.util.Objects;
 
 /**
- * A time signal from a manual (user provided) source. The value consists of the number of
- * milliseconds elapsed since 1/1/1970 00:00:00 UTC and the time according to the elapsed realtime
- * clock when that number was established. The elapsed realtime clock is considered accurate but
- * volatile, so time signals must not be persisted across device resets.
+ * A time signal from a manual (user provided) source.
+ *
+ * <p>{@code utcTime} is the suggested time. The {@code utcTime.value} is the number of milliseconds
+ * elapsed since 1/1/1970 00:00:00 UTC. The {@code utcTime.referenceTimeMillis} is the value of the
+ * elapsed realtime clock when the {@code utcTime.value} was established.
+ * Note that the elapsed realtime clock is considered accurate but it is volatile, so time
+ * suggestions cannot be persisted across device resets.
+ *
+ * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
+ * record why the suggestion exists and how it was entered. This information exists only to aid in
+ * debugging and therefore is used by {@link #toString()}, but it is not for use in detection
+ * logic and is not considered in {@link #hashCode()} or {@link #equals(Object)}.
  *
  * @hide
  */
@@ -49,10 +57,8 @@ public final class ManualTimeSuggestion implements Parcelable {
                 }
             };
 
-    @NonNull
-    private final TimestampedValue<Long> mUtcTime;
-    @Nullable
-    private ArrayList<String> mDebugInfo;
+    @NonNull private final TimestampedValue<Long> mUtcTime;
+    @Nullable private ArrayList<String> mDebugInfo;
 
     public ManualTimeSuggestion(@NonNull TimestampedValue<Long> utcTime) {
         mUtcTime = Objects.requireNonNull(utcTime);
diff --git a/core/java/android/app/timedetector/NetworkTimeSuggestion.java b/core/java/android/app/timedetector/NetworkTimeSuggestion.java
index 17e9c5a79fa5..89fd6f31e042 100644
--- a/core/java/android/app/timedetector/NetworkTimeSuggestion.java
+++ b/core/java/android/app/timedetector/NetworkTimeSuggestion.java
@@ -29,10 +29,18 @@ import java.util.List;
 import java.util.Objects;
 
 /**
- * A time signal from a network time source like NTP. The value consists of the number of
- * milliseconds elapsed since 1/1/1970 00:00:00 UTC and the time according to the elapsed realtime
- * clock when that number was established. The elapsed realtime clock is considered accurate but
- * volatile, so time signals must not be persisted across device resets.
+ * A time signal from a network time source like NTP.
+ *
+ * <p>{@code utcTime} contains the suggested time. The {@code utcTime.value} is the number of
+ * milliseconds elapsed since 1/1/1970 00:00:00 UTC. The {@code utcTime.referenceTimeMillis} is the
+ * value of the elapsed realtime clock when the {@code utcTime.value} was established.
+ * Note that the elapsed realtime clock is considered accurate but it is volatile, so time
+ * suggestions cannot be persisted across device resets.
+ *
+ * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
+ * record why the suggestion exists and how it was determined. This information exists only to aid
+ * in debugging and therefore is used by {@link #toString()}, but it is not for use in detection
+ * logic and is not considered in {@link #hashCode()} or {@link #equals(Object)}.
  *
  * @hide
  */
@@ -49,10 +57,8 @@ public final class NetworkTimeSuggestion implements Parcelable {
                 }
             };
 
-    @NonNull
-    private final TimestampedValue<Long> mUtcTime;
-    @Nullable
-    private ArrayList<String> mDebugInfo;
+    @NonNull private final TimestampedValue<Long> mUtcTime;
+    @Nullable private ArrayList<String> mDebugInfo;
 
     public NetworkTimeSuggestion(@NonNull TimestampedValue<Long> utcTime) {
         mUtcTime = Objects.requireNonNull(utcTime);
diff --git a/core/java/android/app/timedetector/PhoneTimeSuggestion.java b/core/java/android/app/timedetector/PhoneTimeSuggestion.java
index eab88383fa1d..16288e82d452 100644
--- a/core/java/android/app/timedetector/PhoneTimeSuggestion.java
+++ b/core/java/android/app/timedetector/PhoneTimeSuggestion.java
@@ -32,12 +32,22 @@ import java.util.Objects;
  * A time suggestion from an identified telephony source. e.g. from NITZ information from a specific
  * radio.
  *
- * <p>The time value can be {@code null} to indicate that the telephony source has entered an
- * "un-opinionated" state and any previous suggestions from the source are being withdrawn. When not
- * {@code null}, the value consists of the number of milliseconds elapsed since 1/1/1970 00:00:00
- * UTC and the time according to the elapsed realtime clock when that number was established. The
- * elapsed realtime clock is considered accurate but volatile, so time suggestions must not be
- * persisted across device resets.
+ * <p>{@code slotIndex} identifies the suggestion source. This enables detection logic to identify
+ * suggestions from the same source when there are several in use.
+ *
+ * <p>{@code utcTime}. When not {@code null}, the {@code utcTime.value} is the number of
+ * milliseconds elapsed since 1/1/1970 00:00:00 UTC. The {@code utcTime.referenceTimeMillis} is the
+ * value of the elapsed realtime clock when the {@code utcTime.value} was established.
+ * Note that the elapsed realtime clock is considered accurate but it is volatile, so time
+ * suggestions cannot be persisted across device resets. {@code utcTime} can be {@code null} to
+ * indicate that the telephony source has entered an "un-opinionated" state and any previous
+ * suggestion from the source is being withdrawn.
+ *
+ * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
+ * record why the suggestion exists, e.g. what triggered it to be made and what heuristic was used
+ * to determine the time or its absence. This information exists only to aid in debugging and
+ * therefore is used by {@link #toString()}, but it is not for use in detection logic and is not
+ * considered in {@link #hashCode()} or {@link #equals(Object)}.
  *
  * @hide
  */
@@ -93,16 +103,18 @@ public final class PhoneTimeSuggestion implements Parcelable {
     }
 
     /**
-     * Returns an identifier for the source of this suggestion. When a device has several sim slots
-     * or equivalent, it is used to identify which one the suggestion is from.
+     * Returns an identifier for the source of this suggestion.
+     *
+     * <p>See {@link PhoneTimeSuggestion} for more information about {@code slotIndex}.
      */
     public int getSlotIndex() {
         return mSlotIndex;
     }
 
     /**
-     * Returns the suggestion. {@code null} means that the caller is no longer sure what time it
-     * is.
+     * Returns the suggested time or {@code null} if there isn't one.
+     *
+     * <p>See {@link PhoneTimeSuggestion} for more information about {@code utcTime}.
      */
     @Nullable
     public TimestampedValue<Long> getUtcTime() {
@@ -110,8 +122,9 @@ public final class PhoneTimeSuggestion implements Parcelable {
     }
 
     /**
-     * Returns debug metadata for the suggestion. The information is present in {@link #toString()}
-     * but is not considered for {@link #equals(Object)} and {@link #hashCode()}.
+     * Returns debug metadata for the suggestion.
+     *
+     * <p>See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}.
      */
     @NonNull
     public List<String> getDebugInfo() {
@@ -120,9 +133,9 @@ public final class PhoneTimeSuggestion implements Parcelable {
     }
 
     /**
-     * Associates information with the instance that can be useful for debugging / logging. The
-     * information is present in {@link #toString()} but is not considered for
-     * {@link #equals(Object)} and {@link #hashCode()}.
+     * Associates information with the instance that can be useful for debugging / logging.
+     *
+     * <p>See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}.
      */
     public void addDebugInfo(@NonNull String debugInfo) {
         if (mDebugInfo == null) {
@@ -132,9 +145,9 @@ public final class PhoneTimeSuggestion implements Parcelable {
     }
 
     /**
-     * Associates information with the instance that can be useful for debugging / logging. The
-     * information is present in {@link #toString()} but is not considered for
-     * {@link #equals(Object)} and {@link #hashCode()}.
+     * Associates information with the instance that can be useful for debugging / logging.
+     *
+     * <p>See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}.
      */
     public void addDebugInfo(@NonNull List<String> debugInfo) {
         if (mDebugInfo == null) {
@@ -181,12 +194,20 @@ public final class PhoneTimeSuggestion implements Parcelable {
         @Nullable private TimestampedValue<Long> mUtcTime;
         @Nullable private List<String> mDebugInfo;
 
-        /** Creates a builder with the specified {@code slotIndex}. */
+        /**
+         * Creates a builder with the specified {@code slotIndex}.
+         *
+         * <p>See {@link PhoneTimeSuggestion} for more information about {@code slotIndex}.
+         */
         public Builder(int slotIndex) {
             mSlotIndex = slotIndex;
         }
 
-        /** Returns the builder for call chaining. */
+        /**
+         * Returns the builder for call chaining.
+         *
+         * <p>See {@link PhoneTimeSuggestion} for more information about {@code utcTime}.
+         */
         @NonNull
         public Builder setUtcTime(@Nullable TimestampedValue<Long> utcTime) {
             if (utcTime != null) {
@@ -198,7 +219,11 @@ public final class PhoneTimeSuggestion implements Parcelable {
             return this;
         }
 
-        /** Returns the builder for call chaining. */
+        /**
+         * Returns the builder for call chaining.
+         *
+         * <p>See {@link PhoneTimeSuggestion} for more information about {@code debugInfo}.
+         */
         @NonNull
         public Builder addDebugInfo(@NonNull String debugInfo) {
             if (mDebugInfo == null) {
diff --git a/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java b/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java
index a6b953b42f8f..3a9adc72aab1 100644
--- a/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java
+++ b/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java
@@ -28,10 +28,14 @@ import java.util.List;
 import java.util.Objects;
 
 /**
- * A time signal from a manual (user provided) source. The value consists of the number of
- * milliseconds elapsed since 1/1/1970 00:00:00 UTC and the time according to the elapsed realtime
- * clock when that number was established. The elapsed realtime clock is considered accurate but
- * volatile, so time signals must not be persisted across device resets.
+ * A time signal from a manual (user provided) source.
+ *
+ * <p>{@code zoneId} contains the suggested time zone ID, e.g. "America/Los_Angeles".
+ *
+ * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
+ * record why the suggestion exists and how it was entered. This information exists only to aid in
+ * debugging and therefore is used by {@link #toString()}, but it is not for use in detection logic
+ * and is not considered in {@link #hashCode()} or {@link #equals(Object)}.
  *
  * @hide
  */
@@ -48,10 +52,8 @@ public final class ManualTimeZoneSuggestion implements Parcelable {
                 }
             };
 
-    @NonNull
-    private final String mZoneId;
-    @Nullable
-    private ArrayList<String> mDebugInfo;
+    @NonNull private final String mZoneId;
+    @Nullable private ArrayList<String> mDebugInfo;
 
     public ManualTimeZoneSuggestion(@NonNull String zoneId) {
         mZoneId = Objects.requireNonNull(zoneId);
diff --git a/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java b/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java
index ebaf951130ca..0544ccd3f4c5 100644
--- a/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java
+++ b/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java
@@ -34,10 +34,14 @@ import java.util.Objects;
  * A time zone suggestion from an identified telephony source, e.g. from MCC and NITZ information
  * associated with a specific radio.
  *
- * <p>The time zone ID can be {@code null} to indicate that the telephony source has entered an
- * "un-opinionated" state and any previous suggestions from that source are being withdrawn.
- * When not {@code null}, the value consists of a suggested time zone ID and metadata that can be
- * used to judge quality / certainty of the suggestion.
+ * <p>{@code slotIndex} identifies the suggestion source. This enables detection logic to identify
+ * suggestions from the same source when there are several in use.
+ *
+ * <p>{@code zoneId}. When not {@code null}, {@code zoneId} contains the suggested time zone ID,
+ * e.g. "America/Los_Angeles". Suggestion metadata like {@code matchType} and {@code quality} can be
+ * used to judge quality / certainty of the suggestion. {@code zoneId} can be {@code null} to
+ * indicate that the telephony source has entered an "un-opinionated" state and any previous
+ * suggestion from the same source is being withdrawn.
  *
  * <p>{@code matchType} must be set to {@link #MATCH_TYPE_NA} when {@code zoneId} is {@code null},
  * and one of the other {@code MATCH_TYPE_} values when it is not {@code null}.
@@ -45,6 +49,12 @@ import java.util.Objects;
  * <p>{@code quality} must be set to {@link #QUALITY_NA} when {@code zoneId} is {@code null},
  * and one of the other {@code QUALITY_} values when it is not {@code null}.
  *
+ * <p>{@code debugInfo} contains debugging metadata associated with the suggestion. This is used to
+ * record why the suggestion exists, e.g. what triggered it to be made and what heuristic was used
+ * to determine the time zone or its absence. This information exists only to aid in debugging and
+ * therefore is used by {@link #toString()}, but it is not for use in detection logic and is not
+ * considered in {@link #hashCode()} or {@link #equals(Object)}.
+ *
  * @hide
  */
 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
@@ -131,38 +141,11 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
      */
     public static final int QUALITY_MULTIPLE_ZONES_WITH_DIFFERENT_OFFSETS = 3;
 
-    /**
-     * The ID of the phone this suggestion is associated with. For multiple-sim devices this
-     * helps to establish source so filtering / stickiness can be implemented.
-     */
     private final int mSlotIndex;
-
-    /**
-     * The suggestion. {@code null} means there is no current suggestion and any previous suggestion
-     * should be forgotten.
-     */
-    @Nullable
-    private final String mZoneId;
-
-    /**
-     * The type of "match" used to establish the time zone.
-     */
-    @MatchType
-    private final int mMatchType;
-
-    /**
-     * A measure of the quality of the time zone suggestion, i.e. how confident one could be in
-     * it.
-     */
-    @Quality
-    private final int mQuality;
-
-    /**
-     * Free-form debug information about how the suggestion was derived. Used for debug only,
-     * intentionally not used in equals(), etc.
-     */
-    @Nullable
-    private List<String> mDebugInfo;
+    @Nullable private final String mZoneId;
+    @MatchType private final int mMatchType;
+    @Quality private final int mQuality;
+    @Nullable private List<String> mDebugInfo;
 
     private PhoneTimeZoneSuggestion(Builder builder) {
         mSlotIndex = builder.mSlotIndex;
@@ -203,8 +186,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
     }
 
     /**
-     * Returns an identifier for the source of this suggestion. When a device has several sim slots
-     * or equivalent, it is used to identify which one the suggestion is from.
+     * Returns an identifier for the source of this suggestion.
+     *
+     * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code slotIndex}.
      */
     public int getSlotIndex() {
         return mSlotIndex;
@@ -212,8 +196,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
 
     /**
      * Returns the suggested time zone Olson ID, e.g. "America/Los_Angeles". {@code null} means that
-     * the caller is no longer sure what the current time zone is. See
-     * {@link PhoneTimeZoneSuggestion} for the associated {@code matchType} / {@code quality} rules.
+     * the caller is no longer sure what the current time zone is.
+     *
+     * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code zoneId}.
      */
     @Nullable
     public String getZoneId() {
@@ -222,8 +207,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
 
     /**
      * Returns information about how the suggestion was determined which could be used to rank
-     * suggestions when several are available from different sources. See
-     * {@link PhoneTimeZoneSuggestion} for the associated rules.
+     * suggestions when several are available from different sources.
+     *
+     * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code matchType}.
      */
     @MatchType
     public int getMatchType() {
@@ -231,8 +217,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
     }
 
     /**
-     * Returns information about the likelihood of the suggested zone being correct.  See
-     * {@link PhoneTimeZoneSuggestion} for the associated rules.
+     * Returns information about the likelihood of the suggested zone being correct.
+     *
+     * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code quality}.
      */
     @Quality
     public int getQuality() {
@@ -240,8 +227,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
     }
 
     /**
-     * Returns debug metadata for the suggestion. The information is present in {@link #toString()}
-     * but is not considered for {@link #equals(Object)} and {@link #hashCode()}.
+     * Returns debug metadata for the suggestion.
+     *
+     * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}.
      */
     @NonNull
     public List<String> getDebugInfo() {
@@ -250,9 +238,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
     }
 
     /**
-     * Associates information with the instance that can be useful for debugging / logging. The
-     * information is present in {@link #toString()} but is not considered for
-     * {@link #equals(Object)} and {@link #hashCode()}.
+     * Associates information with the instance that can be useful for debugging / logging.
+     *
+     * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}.
      */
     public void addDebugInfo(@NonNull String debugInfo) {
         if (mDebugInfo == null) {
@@ -262,9 +250,9 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
     }
 
     /**
-     * Associates information with the instance that can be useful for debugging / logging. The
-     * information is present in {@link #toString()} but is not considered for
-     * {@link #equals(Object)} and {@link #hashCode()}.
+     * Associates information with the instance that can be useful for debugging / logging.
+     *
+     * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}.
      */
     public void addDebugInfo(@NonNull List<String> debugInfo) {
         if (mDebugInfo == null) {
@@ -317,12 +305,19 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
         @Quality private int mQuality;
         @Nullable private List<String> mDebugInfo;
 
+        /**
+         * Creates a builder with the specified {@code slotIndex}.
+         *
+         * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code slotIndex}.
+         */
         public Builder(int slotIndex) {
             mSlotIndex = slotIndex;
         }
 
         /**
          * Returns the builder for call chaining.
+         *
+         * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code zoneId}.
          */
         @NonNull
         public Builder setZoneId(@Nullable String zoneId) {
@@ -330,21 +325,33 @@ public final class PhoneTimeZoneSuggestion implements Parcelable {
             return this;
         }
 
-        /** Returns the builder for call chaining. */
+        /**
+         * Returns the builder for call chaining.
+         *
+         * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code matchType}.
+         */
         @NonNull
         public Builder setMatchType(@MatchType int matchType) {
             mMatchType = matchType;
             return this;
         }
 
-        /** Returns the builder for call chaining. */
+        /**
+         * Returns the builder for call chaining.
+         *
+         * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code quality}.
+         */
         @NonNull
         public Builder setQuality(@Quality int quality) {
             mQuality = quality;
             return this;
         }
 
-        /** Returns the builder for call chaining. */
+        /**
+         * Returns the builder for call chaining.
+         *
+         * <p>See {@link PhoneTimeZoneSuggestion} for more information about {@code debugInfo}.
+         */
         @NonNull
         public Builder addDebugInfo(@NonNull String debugInfo) {
             if (mDebugInfo == null) {