Merge "More API council tidy up" am: f4e1ac840c am: 5846bfad68
Change-Id: I36387502a6f2202001076f1fac40708e87e9ae70
diff --git a/api/module-lib-current.txt b/api/module-lib-current.txt
index 278a186..8ba204c 100644
--- a/api/module-lib-current.txt
+++ b/api/module-lib-current.txt
@@ -87,8 +87,8 @@
method @NonNull public java.util.List<android.timezone.CountryTimeZones.TimeZoneMapping> getEffectiveTimeZoneMappingsAt(long);
method public boolean hasUtcZone(long);
method public boolean isDefaultTimeZoneBoosted();
- method public boolean isForCountryCode(@NonNull String);
method @Nullable public android.timezone.CountryTimeZones.OffsetResult lookupByOffsetWithBias(int, @Nullable Boolean, @Nullable Integer, long, @Nullable android.icu.util.TimeZone);
+ method public boolean matchesCountryCode(@NonNull String);
}
public static final class CountryTimeZones.OffsetResult {
@@ -98,7 +98,7 @@
}
public static final class CountryTimeZones.TimeZoneMapping {
- method @Nullable public android.icu.util.TimeZone getTimeZone();
+ method @NonNull public android.icu.util.TimeZone getTimeZone();
method @NonNull public String getTimeZoneId();
}
diff --git a/core/java/android/timezone/CountryTimeZones.java b/core/java/android/timezone/CountryTimeZones.java
index 5875761..970acd0 100644
--- a/core/java/android/timezone/CountryTimeZones.java
+++ b/core/java/android/timezone/CountryTimeZones.java
@@ -51,8 +51,10 @@
}
/**
- * Returns the ID for this mapping. See also {@link #getTimeZone()} which handles when the
- * ID is unrecognized.
+ * Returns the ID for this mapping. The ID is a tzdb time zone identifier like
+ * "America/Los_Angeles" that can be used with methods such as {@link
+ * TimeZone#getFrozenTimeZone(String)}. See {@link #getTimeZone()} which returns a frozen
+ * {@link TimeZone} object.
*/
@NonNull
public String getTimeZoneId() {
@@ -60,10 +62,9 @@
}
/**
- * Returns a {@link TimeZone} object for this mapping, or {@code null} if the ID is
- * unrecognized.
+ * Returns a frozen {@link TimeZone} object for this mapping.
*/
- @Nullable
+ @NonNull
public TimeZone getTimeZone() {
return mDelegate.getTimeZone();
}
@@ -158,9 +159,10 @@
}
/**
- * Returns true if the ISO code for the country is a match for the one specified.
+ * Returns true if the ISO code for the country is a case-insensitive match for the one
+ * supplied.
*/
- public boolean isForCountryCode(@NonNull String countryIso) {
+ public boolean matchesCountryCode(@NonNull String countryIso) {
return mDelegate.isForCountryCode(countryIso);
}
@@ -183,15 +185,25 @@
}
/**
- * Qualifier for a country's default time zone. {@code true} indicates whether the default
- * would be a good choice <em>generally</em> when there's no other information available.
+ * Qualifier for a country's default time zone. {@code true} indicates that the country's
+ * default time zone would be a good choice <em>generally</em> when there's no UTC offset
+ * information available. This will only be {@code true} in countries with multiple zones where
+ * a large majority of the population is covered by only one of them.
*/
public boolean isDefaultTimeZoneBoosted() {
return mDelegate.isDefaultTimeZoneBoosted();
}
/**
- * Returns true if the country has at least one zone that is the same as UTC at the given time.
+ * Returns {@code true} if the country has at least one time zone that uses UTC at the given
+ * time. This is an efficient check when trying to validate received UTC offset information.
+ * For example, there are situations when a detected zero UTC offset cannot be distinguished
+ * from "no information available" or a corrupted signal. This method is useful because checking
+ * offset information for large countries is relatively expensive but it is generally only the
+ * countries close to the prime meridian that use UTC at <em>any</em> time of the year.
+ *
+ * @param whenMillis the time the offset information is for in milliseconds since the beginning
+ * of the Unix epoch
*/
public boolean hasUtcZone(long whenMillis) {
return mDelegate.hasUtcZone(whenMillis);