API docs tidy up
Based on feedback from API council.
Bug: 148402959
Bug: 148402200
Test: treehugger only
Change-Id: I273ced8ec61dd72d8fd290b976ecfe1e613a1941
diff --git a/core/java/android/app/timedetector/ManualTimeSuggestion.java b/core/java/android/app/timedetector/ManualTimeSuggestion.java
index 50de7385..da51ce2 100644
--- a/core/java/android/app/timedetector/ManualTimeSuggestion.java
+++ b/core/java/android/app/timedetector/ManualTimeSuggestion.java
@@ -29,10 +29,18 @@
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 @@
}
};
- @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 17e9c5a..89fd6f31 100644
--- a/core/java/android/app/timedetector/NetworkTimeSuggestion.java
+++ b/core/java/android/app/timedetector/NetworkTimeSuggestion.java
@@ -29,10 +29,18 @@
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 @@
}
};
- @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 eab8838..16288e8 100644
--- a/core/java/android/app/timedetector/PhoneTimeSuggestion.java
+++ b/core/java/android/app/timedetector/PhoneTimeSuggestion.java
@@ -32,12 +32,22 @@
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
@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 @@
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 a6b953b..3a9adc7 100644
--- a/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java
+++ b/core/java/android/app/timezonedetector/ManualTimeZoneSuggestion.java
@@ -28,10 +28,14 @@
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 @@
}
};
- @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 ebaf951..0544ccd 100644
--- a/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java
+++ b/core/java/android/app/timezonedetector/PhoneTimeZoneSuggestion.java
@@ -34,10 +34,14 @@
* 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 @@
* <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 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 @@
}
/**
- * 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 @@
/**
* 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
@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 @@
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) {