ICU-4623 document calendar preferred instantiation

X-SVN-Rev: 18152

icu4j/src/com/ibm/icu/util/BuddhistCalendar.java

@@ -25,7 +25,14 @@ import java.util.Locale;
  * The Buddhist Calendar has only one allowable era: <code>BE</code>.  If the
  * calendar is not in lenient mode (see <code>setLenient</code>), dates before
  * 1/1/1 BE are rejected with an <code>IllegalArgumentException</code>.
- *
+ * <p>
+ * This class should not be subclassed.</p>
+ * <p>
+ * BuddhistCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=buddhist"</code>.</p>
+ * 
+ * @see com.ibm.icu.util.Calendar
  * @see com.ibm.icu.util.GregorianCalendar
  *
  * @author Laura Werner

icu4j/src/com/ibm/icu/util/Calendar.java

@@ -59,14 +59,22 @@ import java.util.Set;
  * Like other locale-sensitive classes, <code>Calendar</code> provides a
  * class method, <code>getInstance</code>, for getting a generally useful
  * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
- * returns a <code>GregorianCalendar</code> object whose
+ * returns a calendar of a type appropriate to the locale, whose
  * time fields have been initialized with the current date and time:
  * <blockquote>
- * <pre>
- * Calendar rightNow = Calendar.getInstance();
- * </pre>
+ * <pre>Calendar rightNow = Calendar.getInstance()</pre>
  * </blockquote>
  *
+ * <p>When a <code>ULocale</code> is used by <code>getInstance</code>, its
+ * '<code>calendar</code>' tag and value are retrieved if present.  If a recognized
+ * value is supplied, a calendar is provided and configured as appropriate.
+ * Currently recognized tags are "buddhist", "chinese", "coptic", "ethiopic", 
+ * "gregorian", "hebrew", "islamic", "islamic-civil", and "japanese".  For
+ * example: <blockquote>
+ * <pre>Calendar cal = Calendar.getInstance(new ULocale("en_US@calendar=japanese"));</pre>
+ * </blockquote> will return an instance of JapaneseCalendar (using en_US conventions for
+ * minimum days in first week, start day of week, et cetera).
+ *
  * <p>A <code>Calendar</code> object can produce all the time field values
  * needed to implement the date-time formatting for a particular language and
  * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
@@ -130,8 +138,7 @@ import java.util.Set;
  * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
  * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
  * DAY_OF_YEAR
- * DAY_OF_WEEK + WEEK_OF_YEAR
- * </pre>
+ * DAY_OF_WEEK + WEEK_OF_YEAR</pre>
  * </blockquote>
  *
  * For the time of day:
@@ -139,8 +146,7 @@ import java.util.Set;
  * <blockquote>
  * <pre>
  * HOUR_OF_DAY
- * AM_PM + HOUR
- * </pre>
+ * AM_PM + HOUR</pre>
  * </blockquote>
  *
  * <p>
@@ -1596,7 +1602,7 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable {
     }
 
     /**
-     * Gets a calendar using the default time zone and specified locale.
+     * Gets a calendar using the default time zone and specified locale.  
      * @param locale the ulocale for the week data
      * @return a Calendar.
      * @draft ICU 3.2

icu4j/src/com/ibm/icu/util/ChineseCalendar.java

@@ -67,7 +67,15 @@ import java.util.Locale;
  *
  * </ul>
  *
+ * <p>
+ * This class should not be subclassed.</p>
+ * <p>
+ * ChineseCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=chinese"</code>.</p>
+ *
  * @see com.ibm.icu.text.ChineseDateFormat
+ * @see com.ibm.icu.util.Calendar
  * @author Alan Liu
  * @stable ICU 2.8
  */

icu4j/src/com/ibm/icu/util/CopticCalendar.java

@@ -11,6 +11,12 @@ import java.util.Locale;
 
 /**
  * Implement the Coptic calendar system.
+ * <p>
+ * CopticCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=coptic"</code>.</p>
+ *
+ * @see com.ibm.icu.util.Calendar
  * @draft ICU 3.4
  * @deprecated This is a draft API and might change in a future release of ICU.
  */

icu4j/src/com/ibm/icu/util/EthiopicCalendar.java

@@ -11,6 +11,12 @@ import java.util.Locale;
 
 /**
  * Implement the Ethiopic calendar system.
+ * <p>
+ * EthiopicCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=ethiopic"</code>.</p>
+ *
+ * @see com.ibm.icu.util.Calendar
  * @draft ICU 3.4
  * @deprecated This is a draft API and might change in a future release of ICU.
  */

icu4j/src/com/ibm/icu/util/GregorianCalendar.java

@@ -155,10 +155,13 @@ import java.util.Locale;
  * System.out.println("ZONE_OFFSET: "
  *        + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
  * System.out.println("DST_OFFSET: "
- *        + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours
- * </pre>
+ *        + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours</pre>
  * </blockquote>
- *
+ * <p>
+ * GregorianCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=gregorian"</code>.</p>
+
  * @see          Calendar
  * @see          TimeZone
  * @author David Goldsmith, Mark Davis, Chen-Lieh Huang, Alan Liu

icu4j/src/com/ibm/icu/util/HebrewCalendar.java

@@ -55,9 +55,16 @@ import java.util.Locale;
  *      <a href="http://www.faqs.org/faqs/calendars/faq/">
  *      http://www.faqs.org/faqs/calendars/faq/</a>
  * </ul>
+ *
  * <p>
+ * This class should not be subclassed.</p>
+ * <p>
+ * HebrewCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=hebrew"</code>.</p>
  *
  * @see com.ibm.icu.util.GregorianCalendar
+ * @see com.ibm.icu.util.Calendar
  *
  * @author Laura Werner
  * @author Alan Liu
@@ -841,8 +848,6 @@ public class HebrewCalendar extends Calendar {
         return "hebrew";
     }
 
-    
-
     /*
     private static CalendarFactory factory;
     public static CalendarFactory factory() {

icu4j/src/com/ibm/icu/util/IslamicCalendar.java

@@ -61,8 +61,14 @@ import java.util.Locale;
  * fixed-cycle civil calendar is used.  However, if <code>setCivil(false)</code>
  * is called, an approximation of the true lunar calendar will be used.
  * <p>
+ * This class should not be subclassed.</p>
+ * <p>
+ * IslamicCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=islamic"</code> or <code>"@calendar=islamic-civil"</code>.</p>
  *
  * @see com.ibm.icu.util.GregorianCalendar
+ * @see com.ibm.icu.util.Calendar
  *
  * @author Laura Werner
  * @author Alan Liu

icu4j/src/com/ibm/icu/util/JapaneseCalendar.java

@@ -33,7 +33,14 @@ import java.util.Locale;
  * may change in the future as we add more historical data.  Use the predefined
  * constants rather than using actual, absolute numbers.
  * <p>
+ * This class should not be subclassed.</p>
+ * <p>
+ * JapaneseCalendar usually should be instantiated using 
+ * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
+ * with the tag <code>"@calendar=japanese"</code>.</p>
+ *
  * @see com.ibm.icu.util.GregorianCalendar
+ * @see com.ibm.icu.util.Calendar
  *
  * @author Laura Werner
  * @author Alan Liu