ICU-9475 Some additional notes in TimeZoneNames API reference.

X-SVN-Rev: 33228

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/TimeZoneNames.java b/icu4j/main/classes/core/src/com/ibm/icu/text/TimeZoneNames.java
index febe69a8c7accbce363d996beba6d07a2e6fc311..bc6a398f34452ff410235a93358bf174df7c7697 100644 (file)
--- a/icu4j/main/classes/core/src/com/ibm/icu/text/TimeZoneNames.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/text/TimeZoneNames.java
@@ -63,6 +63,13 @@ import com.ibm.icu.util.ULocale;
  * may provide time zone names only through {@link #getTimeZoneDisplayName(String, NameType)}, or only through
  * {@link #getMetaZoneDisplayName(String, NameType)}, or both.
  * 
+ * <p>
+ * The default <code>TimeZoneNames</code> implementation returned by {@link #getInstance(ULocale)} uses the locale data
+ * imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone IDs are shared by all
+ * locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs()}, {@link #getAvailableMetaZoneIDs(String)},
+ * {@link #getMetaZoneID(String, long)}, and {@link #getReferenceZoneID(String, String)} won't be changed no matter
+ * what locale is used for getting an instance of <code>TimeZoneNames</code>.
+ *
  * @draft ICU 49
  * @provisional This API might change or be removed in a future release.
  */
@@ -211,6 +218,11 @@ public abstract class TimeZoneNames implements Serializable {
     /**
      * Returns the reference zone ID for the given meta zone ID for the region.
      * 
+     * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
+     * Some meta zones may have region specific reference zone IDs other than the special region
+     * "001". When a meta zone does not have any region specific reference zone IDs, this method
+     * return the reference zone ID for the special region "001" (world).
+     * 
      * @param mzID
      *            The meta zone ID.
      * @param region