Merge "Fix TextClock documentation Bug #8670351"
diff --git a/core/java/android/widget/TextClock.java b/core/java/android/widget/TextClock.java
index a564c96..b3b95d9 100644
--- a/core/java/android/widget/TextClock.java
+++ b/core/java/android/widget/TextClock.java
@@ -95,6 +95,7 @@
*
* @see #setFormat12Hour(CharSequence)
* @see #getFormat12Hour()
+ *
* @deprecated Let the system use locale-appropriate defaults instead.
*/
public static final CharSequence DEFAULT_FORMAT_12_HOUR = "h:mm a";
@@ -108,6 +109,7 @@
*
* @see #setFormat24Hour(CharSequence)
* @see #getFormat24Hour()
+ *
* @deprecated Let the system use locale-appropriate defaults instead.
*/
public static final CharSequence DEFAULT_FORMAT_24_HOUR = "H:mm";
@@ -162,9 +164,7 @@
};
/**
- * Creates a new clock using the default patterns
- * {@link #DEFAULT_FORMAT_24_HOUR} and {@link #DEFAULT_FORMAT_12_HOUR}
- * respectively for the 24-hour and 12-hour modes.
+ * Creates a new clock using the default patterns for the current locale.
*
* @param context The Context the view is running in, through which it can
* access the current theme, resources, etc.
@@ -258,20 +258,26 @@
}
/**
- * Specifies the formatting pattern used to display the date and/or time
+ * <p>Specifies the formatting pattern used to display the date and/or time
* in 12-hour mode. The formatting pattern syntax is described in
- * {@link DateFormat}.
+ * {@link DateFormat}.</p>
*
- * If this pattern is set to null, {@link #getFormat24Hour()} will be used
+ * <p>If this pattern is set to null, {@link #getFormat24Hour()} will be used
* even in 12-hour mode. If both 24-hour and 12-hour formatting patterns
- * are set to null, {@link #DEFAULT_FORMAT_24_HOUR} and
- * {@link #DEFAULT_FORMAT_12_HOUR} will be used instead.
+ * are set to null, the default pattern for the current locale will be used
+ * instead.</p>
+ *
+ * <p><strong>Note:</strong> if styling is not needed, it is highly recommended
+ * you supply a format string generated by
+ * {@link DateFormat#getBestDateTimePattern(java.util.Locale, String)}. This method
+ * takes care of generating a format string adapted to the desired locale.</p>
+ *
*
* @param format A date/time formatting pattern as described in {@link DateFormat}
*
* @see #getFormat12Hour()
* @see #is24HourModeEnabled()
- * @see #DEFAULT_FORMAT_12_HOUR
+ * @see DateFormat#getBestDateTimePattern(java.util.Locale, String)
* @see DateFormat
*
* @attr ref android.R.styleable#TextClock_format12Hour
@@ -300,20 +306,25 @@
}
/**
- * Specifies the formatting pattern used to display the date and/or time
+ * <p>Specifies the formatting pattern used to display the date and/or time
* in 24-hour mode. The formatting pattern syntax is described in
- * {@link DateFormat}.
+ * {@link DateFormat}.</p>
*
- * If this pattern is set to null, {@link #getFormat12Hour()} will be used
- * even in 24-hour mode. If both 24-hour and 12-hour formatting patterns
- * are set to null, {@link #DEFAULT_FORMAT_24_HOUR} and
- * {@link #DEFAULT_FORMAT_12_HOUR} will be used instead.
+ * <p>If this pattern is set to null, {@link #getFormat24Hour()} will be used
+ * even in 12-hour mode. If both 24-hour and 12-hour formatting patterns
+ * are set to null, the default pattern for the current locale will be used
+ * instead.</p>
+ *
+ * <p><strong>Note:</strong> if styling is not needed, it is highly recommended
+ * you supply a format string generated by
+ * {@link DateFormat#getBestDateTimePattern(java.util.Locale, String)}. This method
+ * takes care of generating a format string adapted to the desired locale.</p>
*
* @param format A date/time formatting pattern as described in {@link DateFormat}
*
* @see #getFormat24Hour()
* @see #is24HourModeEnabled()
- * @see #DEFAULT_FORMAT_24_HOUR
+ * @see DateFormat#getBestDateTimePattern(java.util.Locale, String)
* @see DateFormat
*
* @attr ref android.R.styleable#TextClock_format24Hour
@@ -334,8 +345,7 @@
* returned by {@link #getFormat12Hour()} is used instead.
*
* If either one of the formats is null, the other format is used. If
- * both formats are null, the default values {@link #DEFAULT_FORMAT_12_HOUR}
- * and {@link #DEFAULT_FORMAT_24_HOUR} are used instead.
+ * both formats are null, the default formats for the current locale are used.
*
* @return true if time should be displayed in 24-hour format, false if it
* should be displayed in 12-hour format.