--- a/src/share/classes/java/text/DateFormat.java	Thu Apr 15 11:51:48 2010 -0700
+++ b/src/share/classes/java/text/DateFormat.java	Fri Apr 16 15:53:18 2010 +0900
@@ -53,20 +53,20 @@
 import sun.util.LocaleServiceProviderPool;
 
 /**
- * DateFormat is an abstract class for date/time formatting subclasses which
+ * {@code DateFormat} is an abstract class for date/time formatting subclasses which
  * formats and parses dates or time in a language-independent manner.
- * The date/time formatting subclass, such as SimpleDateFormat, allows for
+ * The date/time formatting subclass, such as {@link SimpleDateFormat}, allows for
  * formatting (i.e., date -> text), parsing (text -> date), and
  * normalization.  The date is represented as a <code>Date</code> object or
  * as the milliseconds since January 1, 1970, 00:00:00 GMT.
  *
- * <p>DateFormat provides many class methods for obtaining default date/time
+ * <p>{@code DateFormat} provides many class methods for obtaining default date/time
  * formatters based on the default or a given locale and a number of formatting
- * styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More
+ * styles. The formatting styles include {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, and {@link #SHORT}. More
  * detail and examples of using these styles are provided in the method
  * descriptions.
  *
- * <p>DateFormat helps you to format and parse dates for any locale.
+ * <p>{@code DateFormat} helps you to format and parse dates for any locale.
  * Your code can be completely independent of the locale conventions for
  * months, days of the week, or even the calendar format: lunar vs. solar.
  *
@@ -86,7 +86,7 @@
  *  }
  * </pre>
  * <p>To format a date for a different Locale, specify it in the
- * call to getDateInstance().
+ * call to {@link #getDateInstance(int, Locale) getDateInstance()}.
  * <pre>
  *  DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);
  * </pre>
@@ -94,30 +94,30 @@
  * <pre>
  *  myDate = df.parse(myString);
  * </pre>
- * <p>Use getDateInstance to get the normal date format for that country.
+ * <p>Use {@code getDateInstance} to get the normal date format for that country.
  * There are other static factory methods available.
- * Use getTimeInstance to get the time format for that country.
- * Use getDateTimeInstance to get a date and time format. You can pass in
+ * Use {@code getTimeInstance} to get the time format for that country.
+ * Use {@code getDateTimeInstance} to get a date and time format. You can pass in
  * different options to these factory methods to control the length of the
- * result; from SHORT to MEDIUM to LONG to FULL. The exact result depends
+ * result; from {@link #SHORT} to {@link #MEDIUM} to {@link #LONG} to {@link #FULL}. The exact result depends
  * on the locale, but generally:
- * <ul><li>SHORT is completely numeric, such as 12.13.52 or 3:30pm
- * <li>MEDIUM is longer, such as Jan 12, 1952
- * <li>LONG is longer, such as January 12, 1952 or 3:30:32pm
- * <li>FULL is pretty completely specified, such as
- * Tuesday, April 12, 1952 AD or 3:30:42pm PST.
+ * <ul><li>{@link #SHORT} is completely numeric, such as {@code 12.13.52} or {@code 3:30pm}
+ * <li>{@link #MEDIUM} is longer, such as {@code Jan 12, 1952}
+ * <li>{@link #LONG} is longer, such as {@code January 12, 1952} or {@code 3:30:32pm}
+ * <li>{@link #FULL} is pretty completely specified, such as
+ * {@code Tuesday, April 12, 1952 AD or 3:30:42pm PST}.
  * </ul>
  *
  * <p>You can also set the time zone on the format if you wish.
  * If you want even more control over the format or parsing,
  * (or want to give your users more control),
- * you can try casting the DateFormat you get from the factory methods
- * to a SimpleDateFormat. This will work for the majority
- * of countries; just remember to put it in a try block in case you
+ * you can try casting the {@code DateFormat} you get from the factory methods
+ * to a {@link SimpleDateFormat}. This will work for the majority
+ * of countries; just remember to put it in a {@code try} block in case you
  * encounter an unusual one.
  *
  * <p>You can also use forms of the parse and format methods with
- * ParsePosition and FieldPosition to
+ * {@link ParsePosition} and {@link FieldPosition} to
  * allow you to
  * <ul><li>progressively parse through pieces of a string.
  * <li>align any particular field, or find out where it is for selection
@@ -143,10 +143,13 @@
 public abstract class DateFormat extends Format {
 
     /**
-     * The calendar that <code>DateFormat</code> uses to produce the time field
-     * values needed to implement date and time formatting.  Subclasses should
-     * initialize this to a calendar appropriate for the locale associated with
-     * this <code>DateFormat</code>.
+     * The {@link Calendar} instance used for calculating the date-time fields
+     * and the instant of time. This field is used for both formatting and
+     * parsing.
+     *
+     * <p>Subclasses should initialize this field to a {@link Calendar}
+     * appropriate for the {@link Locale} associated with this
+     * <code>DateFormat</code>.
      * @serial
      */
     protected Calendar calendar;
@@ -358,15 +361,21 @@
 
     /**
      * Parse a date/time string according to the given parse position.  For
-     * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date
-     * that is equivalent to Date(837039928046).
+     * example, a time text {@code "07/10/96 4:5 PM, PDT"} will be parsed into a {@code Date}
+     * that is equivalent to {@code Date(837039900000L)}.
      *
      * <p> By default, parsing is lenient: If the input is not in the form used
      * by this object's format method but can still be parsed as a date, then
      * the parse succeeds.  Clients may insist on strict adherence to the
-     * format by calling setLenient(false).
+     * format by calling {@link #setLenient(boolean) setLenient(false)}.
      *
-     * @see java.text.DateFormat#setLenient(boolean)
+     * <p>This parsing operation uses the {@link #calendar} to produce
+     * a {@code Date}. As a result, the {@code calendar}'s date-time
+     * fields and the {@code TimeZone} value may have been
+     * overwritten, depending on subclass implementations. Any {@code
+     * TimeZone} value that has previously been set by a call to
+     * {@link #setTimeZone(java.util.TimeZone) setTimeZone} may need
+     * to be restored for further operations.
      *
      * @param source  The date/time string to be parsed
      *
@@ -374,7 +383,7 @@
      *              output, the position at which parsing terminated, or the
      *              start position if the parse failed.
      *
-     * @return      A Date, or null if the input could not be parsed
+     * @return      A {@code Date}, or {@code null} if the input could not be parsed
      */
     public abstract Date parse(String source, ParsePosition pos);
 
@@ -569,7 +578,12 @@
     /**
      * Set the calendar to be used by this date format.  Initially, the default
      * calendar for the specified or default locale is used.
-     * @param newCalendar the new Calendar to be used by the date format
+     *
+     * <p>Any {@link java.util.TimeZone TimeZone} and {@linkplain
+     * #isLenient() leniency} values that have previously been set are
+     * overwritten by {@code newCalendar}'s values.
+     *
+     * @param newCalendar the new {@code Calendar} to be used by the date format
      */
     public void setCalendar(Calendar newCalendar)
     {
@@ -578,6 +592,7 @@
 
     /**
      * Gets the calendar associated with this date/time formatter.
+     *
      * @return the calendar associated with this date/time formatter.
      */
     public Calendar getCalendar()
@@ -605,7 +620,18 @@
     }
 
     /**
-     * Sets the time zone for the calendar of this DateFormat object.
+     * Sets the time zone for the calendar of this {@code DateFormat} object.
+     * This method is equivalent to the following call.
+     * <blockquote><pre>
+     *  getCalendar().setTimeZone(zone)
+     * </pre></blockquote>
+     *
+     * <p>The {@code TimeZone} set by this method is overwritten by a
+     * {@link #setCalendar(java.util.Calendar) setCalendar} call.
+     *
+     * <p>The {@code TimeZone} set by this method may be overwritten as
+     * a result of a call to the parse method.
+     *
      * @param zone the given new time zone.
      */
     public void setTimeZone(TimeZone zone)
@@ -615,6 +641,11 @@
 
     /**
      * Gets the time zone.
+     * This method is equivalent to the following call.
+     * <blockquote><pre>
+     *  getCalendar().getTimeZone()
+     * </pre></blockquote>
+     *
      * @return the time zone associated with the calendar of DateFormat.
      */
     public TimeZone getTimeZone()
@@ -627,8 +658,17 @@
      * lenient parsing, the parser may use heuristics to interpret inputs that
      * do not precisely match this object's format.  With strict parsing,
      * inputs must match this object's format.
-     * @param lenient when true, parsing is lenient
-     * @see java.util.Calendar#setLenient
+     *
+     * <p>This method is equivalent to the following call.
+     * <blockquote><pre>
+     *  getCalendar().setLenient(lenient)
+     * </pre></blockquote>
+     *
+     * <p>This leniency value is overwritten by a call to {@link
+     * #setCalendar(java.util.Calendar) setCalendar()}.
+     *
+     * @param lenient when {@code true}, parsing is lenient
+     * @see java.util.Calendar#setLenient(boolean)
      */
     public void setLenient(boolean lenient)
     {
@@ -637,6 +677,14 @@
 
     /**
      * Tell whether date/time parsing is to be lenient.
+     * This method is equivalent to the following call.
+     * <blockquote><pre>
+     *  getCalendar().isLenient()
+     * </pre></blockquote>
+     *
+     * @return {@code true} if the {@link #calendar} is lenient;
+     *         {@code false} otherwise.
+     * @see java.util.Calendar#isLenient()
      */
     public boolean isLenient()
     {

--- a/src/share/classes/java/text/SimpleDateFormat.java	Thu Apr 15 11:51:48 2010 -0700
+++ b/src/share/classes/java/text/SimpleDateFormat.java	Fri Apr 16 15:53:18 2010 +0900
@@ -1235,6 +1235,20 @@
      * changed, the error index of <code>pos</code> is set to the index of
      * the character where the error occurred, and null is returned.
      *
+     * <p>This parsing operation uses the {@link DateFormat#calendar
+     * calendar} to produce a {@code Date}. All of the {@code
+     * calendar}'s date-time fields are {@linkplain Calendar#clear()
+     * cleared} before parsing, and the {@code calendar}'s default
+     * values of the date-time fields are used for any missing
+     * date-time information. For example, the year value of the
+     * parsed {@code Date} is 1970 with {@link GregorianCalendar} if
+     * no year value is given from the parsing operation.  The {@code
+     * TimeZone} value may be overwritten, depending on the given
+     * pattern and the time zone value in {@code text}. Any {@code
+     * TimeZone} value that has previously been set by a call to
+     * {@link #setTimeZone(java.util.TimeZone) setTimeZone} may need
+     * to be restored for further operations.
+     *
      * @param text  A <code>String</code>, part of which should be parsed.
      * @param pos   A <code>ParsePosition</code> object with index and error
      *              index information as described above.