Fix TextClock documentation

Bug #8670351

Change-Id: I87a906b85b51f44d9dcecb6f137db53886323ad7

1 files changed, 28 insertions, 18 deletions

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 @@ public class TextClock extends TextView {
      *
      * @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 @@ public class TextClock extends TextView {
      *
      * @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 @@ public class TextClock extends TextView {
     };
 
     /**
-     * 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 @@ public class TextClock extends TextView {
     }
 
     /**
-     * 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 @@ public class TextClock extends TextView {
     }
 
     /**
-     * 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>
+     *
+     * <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>
      *
-     * 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><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 @@ public class TextClock extends TextView {
      * 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.