From 2193ad4563028da22ded7d7b7bf8bd8dc143e66c Mon Sep 17 00:00:00 2001 From: Travis Keep Date: Wed, 5 Jun 2013 21:33:31 +0000 Subject: [PATCH] ICU-10202 Fix documentation on getXXXInstance() methods. X-SVN-Rev: 33806 --- .../core/src/com/ibm/icu/text/DateFormat.java | 89 +++++++++++++++++-- 1 file changed, 80 insertions(+), 9 deletions(-) diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java index 6a7faff8351..0968866f218 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java @@ -1676,7 +1676,11 @@ public abstract class DateFormat extends UFormat { } /** - * Convenience overload. + * Returns a date/time formatter that uses the SHORT style + * for both the date and the time. + * + * @param cal The calendar system for which a date/time format is desired. + * @param locale The locale for which the date/time format is desired. * @stable ICU 2.0 */ static final public DateFormat getInstance(Calendar cal, Locale locale) { @@ -1684,7 +1688,11 @@ public abstract class DateFormat extends UFormat { } /** - * Convenience overload. + * Returns a date/time formatter that uses the SHORT style + * for both the date and the time. + * + * @param cal The calendar system for which a date/time format is desired. + * @param locale The locale for which the date/time format is desired. * @stable ICU 3.2 * @provisional This API might change or be removed in a future release. */ @@ -1693,7 +1701,10 @@ public abstract class DateFormat extends UFormat { } /** - * Convenience overload. + * Returns a default date/time formatter that uses the SHORT style for both the + * date and the time. + * + * @param cal The calendar system for which a date/time format is desired. * @stable ICU 2.0 */ static final public DateFormat getInstance(Calendar cal) { @@ -1701,7 +1712,14 @@ public abstract class DateFormat extends UFormat { } /** - * Convenience overload. + * Creates a {@link DateFormat} object for the default locale that can be used + * to format dates in the calendar system specified by cal. + *

+ * @param cal The calendar system for which a date format is desired. + * + * @param dateStyle The type of date format desired. This can be + * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, + * etc. * @stable ICU 2.0 */ static final public DateFormat getDateInstance(Calendar cal, int dateStyle) { @@ -1709,7 +1727,19 @@ public abstract class DateFormat extends UFormat { } /** - * Convenience overload. + * Creates a {@link DateFormat} object that can be used to format times in + * the calendar system specified by cal. + *

+ * Note: When this functionality is moved into the core JDK, this method + * will probably be replaced by a new overload of {@link DateFormat#getInstance}. + *

+ * @param cal The calendar system for which a time format is desired. + * + * @param timeStyle The type of time format desired. This can be + * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, + * etc. + * + * @see DateFormat#getTimeInstance * @stable ICU 2.0 */ static final public DateFormat getTimeInstance(Calendar cal, int timeStyle) { @@ -1717,7 +1747,23 @@ public abstract class DateFormat extends UFormat { } /** - * Convenience overload. + * Creates a {@link DateFormat} object for the default locale that can be used to format + * dates and times in the calendar system specified by cal. + *

+ * Note: When this functionality is moved into the core JDK, this method + * will probably be replaced by a new overload of {@link DateFormat#getInstance}. + *

+ * @param cal The calendar system for which a date/time format is desired. + * + * @param dateStyle The type of date format desired. This can be + * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, + * etc. + * + * @param timeStyle The type of time format desired. This can be + * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, + * etc. + * + * @see DateFormat#getDateTimeInstance * @stable ICU 2.0 */ static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle, int timeStyle) { @@ -1725,7 +1771,13 @@ public abstract class DateFormat extends UFormat { } /** - * {@icu} Convenience overload. + * {@icu} Returns a {@link DateFormat} object that can be used to format dates and times in + * the default locale. + * + * @param skeleton The skeleton that selects the fields to be formatted. (Uses the + * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, + * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. + * * @stable ICU 4.0 */ public final static DateFormat getPatternInstance(String skeleton) { @@ -1733,7 +1785,15 @@ public abstract class DateFormat extends UFormat { } /** - * {@icu} Convenience overload. + * {@icu} Returns a {@link DateFormat} object that can be used to format dates and times in + * the given locale. + * + * @param skeleton The skeleton that selects the fields to be formatted. (Uses the + * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, + * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. + * + * @param locale The locale for which the date/time format is desired. + * * @stable ICU 4.0 */ public final static DateFormat getPatternInstance(String skeleton, Locale locale) { @@ -1759,7 +1819,18 @@ public abstract class DateFormat extends UFormat { } /** - * {@icu} Convenience overload. + * {@icu} Creates a {@link DateFormat} object that can be used to format dates and + * times in the calendar system specified by cal. + * + * @param cal The calendar system for which a date/time format is desired. + * + * @param skeleton The skeleton that selects the fields to be formatted. (Uses the + * {@link DateTimePatternGenerator}.) This can be + * {@link DateFormat#ABBR_MONTH}, {@link DateFormat#MONTH_WEEKDAY_DAY}, + * etc. + * + * @param locale The locale for which the date/time format is desired. + * * @stable ICU 4.0 */ public final static DateFormat getPatternInstance(Calendar cal, String skeleton, Locale locale) { -- 2.40.0