From c5eeb6b6df4ee960e885f711c059291e1a396b0c Mon Sep 17 00:00:00 2001
From: Michael Ow <mow@svn.icu-project.org>
Date: Fri, 11 Nov 2011 23:24:20 +0000
Subject: [PATCH] ICU-8887 Update timezone class doc in ICU4C

X-SVN-Rev: 30956
---
 icu4c/source/i18n/unicode/timezone.h | 11 +++++++----
 icu4c/source/i18n/unicode/ucal.h     |  8 ++++----
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/icu4c/source/i18n/unicode/timezone.h b/icu4c/source/i18n/unicode/timezone.h
index 12263130d1f..0d6e5b7cf61 100644
--- a/icu4c/source/i18n/unicode/timezone.h
+++ b/icu4c/source/i18n/unicode/timezone.h
@@ -82,7 +82,10 @@ class StringEnumeration;
  * For example, you might specify GMT+14:00 as a custom
  * time zone ID.  The <code>TimeZone</code> that is returned
  * when you specify a custom time zone ID does not include
- * daylight savings time.
+ * daylight savings time.  If a custom time zone ID is used,
+ * the meaning of what a positive offset is should also be specified.
+ * In addition, <code>getCanonicalID</code> can also be used to
+ * normalize a custom time zone ID.
  *
  * TimeZone is an abstract class representing a time zone.  A TimeZone is needed for
  * Calendar to produce local time for a particular time zone.  A TimeZone comprises
@@ -98,8 +101,8 @@ class StringEnumeration;
  * </ul>
  *
  * (Only the ID is actually implemented in TimeZone; subclasses of TimeZone may handle
- * daylight savings time and GMT offset in different ways.  Currently we only have one
- * TimeZone subclass: SimpleTimeZone.)
+ * daylight savings time and GMT offset in different ways.  Currently we have the following
+ * TimeZone subclasses: RuleBasedTimeZone, SimpleTimeZone, and VTimeZone.)
  * <P>
  * The TimeZone class contains a static list containing a TimeZone object for every
  * combination of GMT offset and daylight-savings time rules currently in use in the
@@ -160,7 +163,7 @@ public:
      * @param ID the ID for a <code>TimeZone</code>, such as "America/Los_Angeles",
      * or a custom ID such as "GMT-8:00".
      * @return the specified <code>TimeZone</code>, or a mutable clone of getUnknown()
-     * if the given ID cannot be understood.
+     * if the given ID cannot be understood or if the given ID is "Etc/Unknown".
      * The return result is guaranteed to be non-NULL.
      * If you require that the specific zone asked for be returned,
      * compare the result with getUnknown() or check the ID of the return result.
diff --git a/icu4c/source/i18n/unicode/ucal.h b/icu4c/source/i18n/unicode/ucal.h
index a2b0fc4b9cf..b822140d272 100644
--- a/icu4c/source/i18n/unicode/ucal.h
+++ b/icu4c/source/i18n/unicode/ucal.h
@@ -669,10 +669,10 @@ ucal_getNow(void);
  * A UCalendar may be used to convert a millisecond value to a year,
  * month, and day.
  * <p>
- * Note: When unknown TimeZone ID is specified, the UCalendar returned
- * by the function is initialized with GMT zone with TimeZone ID <code>UCAL_UNKNOWN_ZONE_ID</code>
- * ("Etc/Unknown") without any errors/warnings.  If you want to check if a TimeZone ID is valid
- * prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
+ * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
+ * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
+ * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings.  If you want
+ * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
  * 
  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
  * @param len The length of zoneID, or -1 if null-terminated.
-- 
2.40.0