harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [6/12] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Date Thu, 07 May 2009 21:43:44 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java Thu May  7 21:43:41 2009
@@ -22,13 +22,164 @@
 import java.io.ObjectOutputStream;
 
 /**
- * GregorianCalendar provides the conversion between Dates and integer calendar
- * fields, such as the month, year or minute, for the Gregorian calendar. See
- * Calendar for the defined fields.
- * 
+ * {@code GregorianCalendar} is a concrete subclass of {@link Calendar}
+ * and provides the standard calendar used by most of the world.
+ *
+ * <p>
+ * The standard (Gregorian) calendar has 2 eras, BC and AD.
+ *
+ * <p>
+ * This implementation handles a single discontinuity, which corresponds by
+ * default to the date the Gregorian calendar was instituted (October 15, 1582
+ * in some countries, later in others). The cutover date may be changed by the
+ * caller by calling {@code setGregorianChange()}.
+ *
+ * <p>
+ * Historically, in those countries which adopted the Gregorian calendar first,
+ * October 4, 1582 was thus followed by October 15, 1582. This calendar models
+ * this correctly. Before the Gregorian cutover, {@code GregorianCalendar}
+ * implements the Julian calendar. The only difference between the Gregorian and
+ * the Julian calendar is the leap year rule. The Julian calendar specifies leap
+ * years every four years, whereas the Gregorian calendar omits century years
+ * which are not divisible by 400.
+ *
+ * <p>
+ * {@code GregorianCalendar} implements <em>proleptic</em> Gregorian
+ * and Julian calendars. That is, dates are computed by extrapolating the
+ * current rules indefinitely far backward and forward in time. As a result,
+ * {@code GregorianCalendar} may be used for all years to generate
+ * meaningful and consistent results. However, dates obtained using
+ * {@code GregorianCalendar} are historically accurate only from March 1,
+ * 4 AD onward, when modern Julian calendar rules were adopted. Before this
+ * date, leap year rules were applied irregularly, and before 45 BC the Julian
+ * calendar did not even exist.
+ *
+ * <p>
+ * Prior to the institution of the Gregorian calendar, New Year's Day was March
+ * 25. To avoid confusion, this calendar always uses January 1. A manual
+ * adjustment may be made if desired for dates that are prior to the Gregorian
+ * changeover and which fall between January 1 and March 24.
+ *
+ * <p>
+ * Values calculated for the {@code WEEK_OF_YEAR} field range from 1 to
+ * 53. Week 1 for a year is the earliest seven day period starting on
+ * {@code getFirstDayOfWeek()} that contains at least
+ * {@code getMinimalDaysInFirstWeek()} days from that year. It thus
+ * depends on the values of {@code getMinimalDaysInFirstWeek()},
+ * {@code getFirstDayOfWeek()}, and the day of the week of January 1.
+ * Weeks between week 1 of one year and week 1 of the following year are
+ * numbered sequentially from 2 to 52 or 53 (as needed).
+ *
+ * <p>
+ * For example, January 1, 1998 was a Thursday. If
+ * {@code getFirstDayOfWeek()} is {@code MONDAY} and
+ * {@code getMinimalDaysInFirstWeek()} is 4 (these are the values
+ * reflecting ISO 8601 and many national standards), then week 1 of 1998 starts
+ * on December 29, 1997, and ends on January 4, 1998. If, however,
+ * {@code getFirstDayOfWeek()} is {@code SUNDAY}, then week 1 of
+ * 1998 starts on January 4, 1998, and ends on January 10, 1998; the first three
+ * days of 1998 then are part of week 53 of 1997.
+ *
+ * <p>
+ * Values calculated for the {@code WEEK_OF_MONTH} field range from 0 or
+ * 1 to 4 or 5. Week 1 of a month (the days with <code>WEEK_OF_MONTH =
+ * 1</code>)
+ * is the earliest set of at least {@code getMinimalDaysInFirstWeek()}
+ * contiguous days in that month, ending on the day before
+ * {@code getFirstDayOfWeek()}. Unlike week 1 of a year, week 1 of a
+ * month may be shorter than 7 days, need not start on
+ * {@code getFirstDayOfWeek()}, and will not include days of the
+ * previous month. Days of a month before week 1 have a
+ * {@code WEEK_OF_MONTH} of 0.
+ *
+ * <p>
+ * For example, if {@code getFirstDayOfWeek()} is {@code SUNDAY}
+ * and {@code getMinimalDaysInFirstWeek()} is 4, then the first week of
+ * January 1998 is Sunday, January 4 through Saturday, January 10. These days
+ * have a {@code WEEK_OF_MONTH} of 1. Thursday, January 1 through
+ * Saturday, January 3 have a {@code WEEK_OF_MONTH} of 0. If
+ * {@code getMinimalDaysInFirstWeek()} is changed to 3, then January 1
+ * through January 3 have a {@code WEEK_OF_MONTH} of 1.
+ *
+ * <p>
+ * <strong>Example:</strong> <blockquote>
+ *
+ * <pre>
+ * // get the supported ids for GMT-08:00 (Pacific Standard Time)
+ * String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
+ * // if no ids were returned, something is wrong. get out.
+ * if (ids.length == 0)
+ *     System.exit(0);
+ *
+ *  // begin output
+ * System.out.println("Current Time");
+ *
+ * // create a Pacific Standard Time time zone
+ * SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);
+ *
+ * // set up rules for daylight savings time
+ * pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
+ * pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
+ *
+ * // create a GregorianCalendar with the Pacific Daylight time zone
+ * // and the current date and time
+ * Calendar calendar = new GregorianCalendar(pdt);
+ * Date trialTime = new Date();
+ * calendar.setTime(trialTime);
+ *
+ * // print out a bunch of interesting things
+ * System.out.println("ERA: " + calendar.get(Calendar.ERA));
+ * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
+ * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
+ * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
+ * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
+ * System.out.println("DATE: " + calendar.get(Calendar.DATE));
+ * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
+ * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
+ * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
+ * System.out.println("DAY_OF_WEEK_IN_MONTH: "
+ *                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
+ * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
+ * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
+ * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
+ * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
+ * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
+ * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
+ * System.out.println("ZONE_OFFSET: "
+ *                    + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
+ * System.out.println("DST_OFFSET: "
+ *                    + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));
+
+ * System.out.println("Current Time, with hour reset to 3");
+ * calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
+ * calendar.set(Calendar.HOUR, 3);
+ * System.out.println("ERA: " + calendar.get(Calendar.ERA));
+ * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
+ * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
+ * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
+ * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
+ * System.out.println("DATE: " + calendar.get(Calendar.DATE));
+ * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
+ * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
+ * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
+ * System.out.println("DAY_OF_WEEK_IN_MONTH: "
+ *                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
+ * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
+ * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
+ * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
+ * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
+ * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
+ * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
+ * 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>
+ *
+ * </blockquote>
+ *
  * @see Calendar
  * @see TimeZone
- * @see SimpleTimeZone
  */
 public class GregorianCalendar extends Calendar {
 
@@ -81,23 +232,23 @@
     private int lastYearSkew = 0;
 
     /**
-     * Constructs a new GregorianCalendar initialized to the current date and
-     * time.
+     * Constructs a new {@code GregorianCalendar} initialized to the current date and
+     * time with the default {@code Locale} and {@code TimeZone}.
      */
     public GregorianCalendar() {
         this(TimeZone.getDefault(), Locale.getDefault());
     }
 
     /**
-     * Constructs a new GregorianCalendar initialized to midnight in the default
-     * time zone on the specified date.
+     * Constructs a new {@code GregorianCalendar} initialized to midnight in the default
+     * {@code TimeZone} and {@code Locale} on the specified date.
      * 
      * @param year
-     *            the year
+     *            the year.
      * @param month
-     *            the month
+     *            the month.
      * @param day
-     *            the day of the month
+     *            the day of the month.
      */
     public GregorianCalendar(int year, int month, int day) {
         super(TimeZone.getDefault(), Locale.getDefault());
@@ -105,19 +256,19 @@
     }
 
     /**
-     * Constructs a new GregorianCalendar initialized to the specified date and
-     * time.
-     * 
+     * Constructs a new {@code GregorianCalendar} initialized to the specified date and
+     * time in the default {@code TimeZone} and {@code Locale}.
+     *
      * @param year
-     *            the year
+     *            the year.
      * @param month
-     *            the month
+     *            the month.
      * @param day
-     *            the day of the month
+     *            the day of the month.
      * @param hour
-     *            the hour
+     *            the hour.
      * @param minute
-     *            the minute
+     *            the minute.
      */
     public GregorianCalendar(int year, int month, int day, int hour, int minute) {
         super(TimeZone.getDefault(), Locale.getDefault());
@@ -125,21 +276,21 @@
     }
 
     /**
-     * Constructs a new GregorianCalendar initialized to the specified date and
-     * time.
+     * Constructs a new {@code GregorianCalendar} initialized to the specified date and
+     * time in the default {@code TimeZone} and {@code Locale}.
      * 
      * @param year
-     *            the year
+     *            the year.
      * @param month
-     *            the month
+     *            the month.
      * @param day
-     *            the day of the month
+     *            the day of the month.
      * @param hour
-     *            the hour
+     *            the hour.
      * @param minute
-     *            the minute
+     *            the minute.
      * @param second
-     *            the second
+     *            the second.
      */
     public GregorianCalendar(int year, int month, int day, int hour,
             int minute, int second) {
@@ -153,35 +304,35 @@
     }
 
     /**
-     * Constructs a new GregorianCalendar initialized to the current date and
-     * time and using the specified Locale.
+     * Constructs a new {@code GregorianCalendar} initialized to the current date and
+     * time and using the specified {@code Locale} and the default {@code TimeZone}.
      * 
      * @param locale
-     *            the Locale
+     *            the {@code Locale}.
      */
     public GregorianCalendar(Locale locale) {
         this(TimeZone.getDefault(), locale);
     }
 
     /**
-     * Constructs a new GregorianCalendar initialized to the current date and
-     * time and using the specified TimeZone.
+     * Constructs a new {@code GregorianCalendar} initialized to the current date and
+     * time and using the specified {@code TimeZone} and the default {@code Locale}.
      * 
      * @param timezone
-     *            the TimeZone
+     *            the {@code TimeZone}.
      */
     public GregorianCalendar(TimeZone timezone) {
         this(timezone, Locale.getDefault());
     }
 
     /**
-     * Constructs a new GregorianCalendar initialized to the current date and
-     * time and using the specified TimeZone and Locale.
+     * Constructs a new {@code GregorianCalendar} initialized to the current date and
+     * time and using the specified {@code TimeZone} and {@code Locale}.
      * 
      * @param timezone
-     *            the TimeZone
+     *            the {@code TimeZone}.
      * @param locale
-     *            the Locale
+     *            the {@code Locale}.
      */
     public GregorianCalendar(TimeZone timezone, Locale locale) {
         super(timezone, locale);
@@ -195,15 +346,15 @@
     }
 
     /**
-     * Adds the specified amount to a Calendar field.
+     * Adds the specified amount to a {@code Calendar} field.
      * 
      * @param field
-     *            the Calendar field to modify
+     *            the {@code Calendar} field to modify.
      * @param value
-     *            the amount to add to the field
+     *            the amount to add to the field.
      * 
-     * @exception IllegalArgumentException
-     *                when the specified field is DST_OFFSET or ZONE_OFFSET.
+     * @throws IllegalArgumentException
+     *                if the specified field is DST_OFFSET or ZONE_OFFSET.
      */
     @Override
     public void add(int field, int value) {
@@ -299,9 +450,9 @@
     }
 
     /**
-     * Creates new instance of GregorianCalendar with the same properties.
+     * Creates new instance of {@code GregorianCalendar} with the same properties.
      * 
-     * @return a shallow copy of this GregorianCalendar
+     * @return a shallow copy of this {@code GregorianCalendar}.
      */
     @Override
     public Object clone() {
@@ -439,9 +590,6 @@
         }
     }
 
-    /**
-     * Computes the Calendar fields from the time.
-     */
     @Override
     protected void computeFields() {
         int zoneOffset = getTimeZone().getRawOffset();
@@ -544,13 +692,6 @@
         }
     }
 
-    /**
-     * Computes the time from the Calendar fields.
-     * 
-     * @exception IllegalArgumentException
-     *                when the time cannot be computed from the current field
-     *                values
-     */
     @Override
     protected void computeTime() {
         if (!isLenient()) {
@@ -835,19 +976,17 @@
     }
 
     /**
-     * Compares the specified object to this GregorianCalendar and answer if
-     * they are equal. The object must be an instance of GregorianCalendar and
+     * Compares the specified {@code Object} to this {@code GregorianCalendar} and returns whether
+     * they are equal. To be equal, the {@code Object} must be an instance of {@code GregorianCalendar} and
      * have the same properties.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this GregorianCalendar,
-     *         false otherwise
-     * 
-     * @exception IllegalArgumentException
-     *                when the time is not set and the time cannot be computed
-     *                from the current field values
-     * 
+     *            the {@code Object} to compare with this {@code GregorianCalendar}.
+     * @return {@code true} if {@code object} is equal to this
+     *         {@code GregorianCalendar}, {@code false} otherwise.
+     * @throws IllegalArgumentException
+     *                if the time is not set and the time cannot be computed
+     *                from the current field values.
      * @see #hashCode
      */
     @Override
@@ -861,8 +1000,8 @@
      * example, the maximum number of days in the current month.
      * 
      * @param field
-     *            the field
-     * @return the maximum value of the specified field
+     *            the field.
+     * @return the maximum value of the specified field.
      */
     @Override
     public int getActualMaximum(int field) {
@@ -929,11 +1068,11 @@
     /**
      * Gets the minimum value of the specified field for the current date. For
      * the gregorian calendar, this value is the same as
-     * <code>getMinimum()</code>.
+     * {@code getMinimum()}.
      * 
      * @param field
-     *            the field
-     * @return the minimum value of the specified field
+     *            the field.
+     * @return the minimum value of the specified field.
      */
     @Override
     public int getActualMinimum(int field) {
@@ -942,11 +1081,11 @@
 
     /**
      * Gets the greatest minimum value of the specified field. For the gregorian
-     * calendar, this value is the same as <code>getMinimum()</code>.
+     * calendar, this value is the same as {@code getMinimum()}.
      * 
      * @param field
-     *            the field
-     * @return the greatest minimum value of the specified field
+     *            the field.
+     * @return the greatest minimum value of the specified field.
      */
     @Override
     public int getGreatestMinimum(int field) {
@@ -954,10 +1093,10 @@
     }
 
     /**
-     * Answers the gregorian change date of this calendar. This is the date on
+     * Returns the gregorian change date of this calendar. This is the date on
      * which the gregorian calendar came into effect.
      * 
-     * @return a Date which represents the gregorian change date
+     * @return a {@code Date} which represents the gregorian change date.
      */
     public final Date getGregorianChange() {
         return new Date(gregorianCutover);
@@ -968,8 +1107,8 @@
      * for the day of month field.
      * 
      * @param field
-     *            the field
-     * @return the smallest maximum value of the specified field
+     *            the field.
+     * @return the smallest maximum value of the specified field.
      */
     @Override
     public int getLeastMaximum(int field) {
@@ -991,8 +1130,8 @@
      * for the day of month field.
      * 
      * @param field
-     *            the field
-     * @return the greatest maximum value of the specified field
+     *            the field.
+     * @return the greatest maximum value of the specified field.
      */
     @Override
     public int getMaximum(int field) {
@@ -1003,8 +1142,8 @@
      * Gets the smallest minimum value of the specified field.
      * 
      * @param field
-     *            the field
-     * @return the smallest minimum value of the specified field
+     *            the field.
+     * @return the smallest minimum value of the specified field.
      */
     @Override
     public int getMinimum(int field) {
@@ -1061,10 +1200,10 @@
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
+     * Returns an integer hash code for the receiver. Objects which are equal
+     * return the same value for this method.
      * 
-     * @return the receiver's hash
+     * @return the receiver's hash.
      * 
      * @see #equals
      */
@@ -1075,11 +1214,12 @@
     }
 
     /**
-     * Answers if the specified year is a leap year.
+     * Returns whether the specified year is a leap year.
      * 
      * @param year
-     *            the year
-     * @return true if the specified year is a leap year, false otherwise
+     *            the year.
+     * @return {@code true} if the specified year is a leap year, {@code false}
+     *         otherwise.
      */
     public boolean isLeapYear(int year) {
         if (year > changeYear) {
@@ -1110,18 +1250,18 @@
     }
 
     /**
-     * Adds the specified amount the specified field and wrap the value of the
+     * Adds the specified amount the specified field and wraps the value of the
      * field when it goes beyond the maximum or minimum value for the current
      * date. Other fields will be adjusted as required to maintain a consistent
      * date.
      * 
      * @param field
-     *            the field to roll
+     *            the field to roll.
      * @param value
-     *            the amount to add
+     *            the amount to add.
      * 
-     * @exception IllegalArgumentException
-     *                when an invalid field is specified
+     * @throws IllegalArgumentException
+     *                if an invalid field is specified.
      */
     @Override
     public void roll(int field, int value) {
@@ -1227,19 +1367,19 @@
     }
 
     /**
-     * Increment or decrement the specified field and wrap the value of the
+     * Increments or decrements the specified field and wraps the value of the
      * field when it goes beyond the maximum or minimum value for the current
      * date. Other fields will be adjusted as required to maintain a consistent
      * date. For example, March 31 will roll to April 30 when rolling the month
      * field.
      * 
      * @param field
-     *            the field to roll
+     *            the field to roll.
      * @param increment
-     *            true to increment the field, false to decrement
-     * 
-     * @exception IllegalArgumentException
-     *                when an invalid field is specified
+     *            {@code true} to increment the field, {@code false} to
+     *            decrement.
+     * @throws IllegalArgumentException
+     *                if an invalid field is specified.
      */
     @Override
     public void roll(int field, boolean increment) {
@@ -1250,7 +1390,7 @@
      * Sets the gregorian change date of this calendar.
      * 
      * @param date
-     *            a Date which represents the gregorian change date
+     *            a {@code Date} which represents the gregorian change date.
      */
     public void setGregorianChange(Date date) {
         gregorianCutover = date.getTime();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java Thu May  7 21:43:41 2009
@@ -23,11 +23,8 @@
 import java.io.Serializable;
 
 /**
- * HashMap is the hash table based implementation of the Map interface.
- * 
- * This implementation provides all of the optional map operations, and permits
- * null values and the null key. (The HashMap class is roughly equivalent to
- * Hashtable, except that it is unsynchronized and permits nulls.)
+ * HashMap is an implementation of Map. All optional operations (adding and
+ * removing) are supported. Keys and values can be any objects.
  */
 public class HashMap<K, V> extends AbstractMap<K, V> implements Map<K, V>,
         Cloneable, Serializable {
@@ -272,21 +269,19 @@
     }
 
     /**
-     * Constructs a new empty instance of HashMap.
-     *
+     * Constructs a new empty {@code HashMap} instance.
      */
     public HashMap() {
         this(DEFAULT_SIZE);
     }
 
     /**
-     * Constructs a new instance of HashMap with the specified capacity.
+     * Constructs a new {@code HashMap} instance with the specified capacity.
      *
      * @param capacity
-     *            the initial capacity of this HashMap
-     *
-     * @exception IllegalArgumentException
-     *                when the capacity is less than zero
+     *            the initial capacity of this hash map.
+     * @throws IllegalArgumentException
+     *                when the capacity is less than zero.
      */
     public HashMap(int capacity) {
         this(capacity, 0.75f);  // default load factor of 0.75
@@ -317,18 +312,16 @@
     }
 
     /**
-     * Constructs a new instance of HashMap with the specified capacity and load
-     * factor.
-     *
+     * Constructs a new {@code HashMap} instance with the specified capacity and
+     * load factor.
      *
      * @param capacity
-     *            the initial capacity
+     *            the initial capacity of this hash map.
      * @param loadFactor
-     *            the initial load factor
-     *
-     * @exception IllegalArgumentException
+     *            the initial load factor.
+     * @throws IllegalArgumentException
      *                when the capacity is less than zero or the load factor is
-     *                less or equal to zero
+     *                less or equal to zero.
      */
     public HashMap(int capacity, float loadFactor) {
         if (capacity >= 0 && loadFactor > 0) {
@@ -343,11 +336,11 @@
     }
 
     /**
-     * Constructs a new instance of HashMap containing the mappings from the
-     * specified Map.
+     * Constructs a new {@code HashMap} instance containing the mappings from
+     * the specified map.
      *
      * @param map
-     *            the mappings to add
+     *            the mappings to add.
      */
     public HashMap(Map<? extends K, ? extends V> map) {
         this(calculateCapacity(map.size()));
@@ -355,7 +348,7 @@
     }
 
     /**
-     * Removes all mappings from this HashMap, leaving it empty.
+     * Removes all mappings from this hash map, leaving it empty.
      *
      * @see #isEmpty
      * @see #size
@@ -370,11 +363,9 @@
     }
 
     /**
-     * Answers a new HashMap with the same mappings and size as this HashMap.
+     * Returns a shallow copy of this map.
      *
-     * @return a shallow copy of this HashMap
-     *
-     * @see java.lang.Cloneable
+     * @return a shallow copy of this map.
      */
     @Override
     @SuppressWarnings("unchecked")
@@ -399,12 +390,12 @@
     }
 
     /**
-     * Searches this HashMap for the specified key.
+     * Returns whether this map contains the specified key.
      *
      * @param key
-     *            the object to search for
-     * @return true if <code>key</code> is a key of this HashMap, false
-     *         otherwise
+     *            the key to search for.
+     * @return {@code true} if this map contains the specified key,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean containsKey(Object key) {
@@ -413,12 +404,12 @@
     }
 
     /**
-     * Searches this HashMap for the specified value.
+     * Returns whether this map contains the specified value.
      *
      * @param value
-     *            the object to search for
-     * @return true if <code>value</code> is a value of this HashMap, false
-     *         otherwise
+     *            the value to search for.
+     * @return {@code true} if this map contains the specified value,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean containsValue(Object value) {
@@ -447,11 +438,11 @@
     }
 
     /**
-     * Answers a Set of the mappings contained in this HashMap. Each element in
-     * the set is a Map.Entry. The set is backed by this HashMap so changes to
-     * one are reflected by the other. The set does not support adding.
+     * Returns a set containing all of the mappings in this map. Each mapping is
+     * an instance of {@link Map.Entry}. As the set is backed by this map,
+     * changes in one will be reflected in the other.
      *
-     * @return a Set of the mappings
+     * @return a set of the mappings.
      */
     @Override
     public Set<Map.Entry<K, V>> entrySet() {
@@ -459,11 +450,12 @@
     }
 
     /**
-     * Answers the value of the mapping with the specified key.
+     * Returns the value of the mapping with the specified key.
      *
      * @param key
-     *            the key
-     * @return the value of the mapping with the specified key
+     *            the key.
+     * @return the value of the mapping with the specified key, or {@code null}
+     *         if no mapping for the specified key is found.
      */
     @Override
     public V get(Object key) {
@@ -502,11 +494,11 @@
     }
 
     /**
-     * Answers if this HashMap has no elements, a size of zero.
-     *
-     * @return true if this HashMap has no elements, false otherwise
+     * Returns whether this map is empty.
      *
-     * @see #size
+     * @return {@code true} if this map has no elements, {@code false}
+     *         otherwise.
+     * @see #size()
      */
     @Override
     public boolean isEmpty() {
@@ -514,11 +506,11 @@
     }
 
     /**
-     * Answers a Set of the keys contained in this HashMap. The set is backed by
-     * this HashMap so changes to one are reflected by the other. The set does
-     * not support adding.
+     * Returns a set of the keys contained in this map. The set is backed by
+     * this map so changes to one are reflected by the other. The set does not
+     * support adding.
      *
-     * @return a Set of the keys
+     * @return a set of the keys.
      */
     @Override
     public Set<K> keySet() {
@@ -558,11 +550,11 @@
      * Maps the specified key to the specified value.
      *
      * @param key
-     *            the key
+     *            the key.
      * @param value
-     *            the value
-     * @return the value of any previous mapping with the specified key or null
-     *         if there was no mapping
+     *            the value.
+     * @return the value of any previous mapping with the specified key or
+     *         {@code null} if there was no such mapping.
      */
     @Override
     public V put(K key, V value) {
@@ -614,14 +606,14 @@
     }
 
     /**
-     * Copies all the mappings in the given map to this map. These mappings will
-     * replace all mappings that this map had for any of the keys currently in
-     * the given map.
+     * Copies all the mappings in the specified map to this map. These mappings
+     * will replace all mappings that this map had for any of the keys currently
+     * in the given map.
      *
      * @param map
-     *            the Map to copy mappings from
+     *            the map to copy mappings from.
      * @throws NullPointerException
-     *             if the given map is null
+     *             if {@code map} is {@code null}.
      */
     @Override
     public void putAll(Map<? extends K, ? extends V> map) {
@@ -663,12 +655,12 @@
     }
 
     /**
-     * Removes a mapping with the specified key from this HashMap.
+     * Removes the mapping with the specified key from this map.
      *
      * @param key
-     *            the key of the mapping to remove
-     * @return the value of the removed mapping or null if key is not a key in
-     *         this HashMap
+     *            the key of the mapping to remove.
+     * @return the value of the removed mapping or {@code null} if no mapping
+     *         for the specified key was found.
      */
     @Override
     public V remove(Object key) {
@@ -732,9 +724,9 @@
     }
 
     /**
-     * Answers the number of mappings in this HashMap.
+     * Returns the number of elements in this map.
      *
-     * @return the number of mappings in this HashMap
+     * @return the number of elements in this map.
      */
     @Override
     public int size() {
@@ -742,11 +734,23 @@
     }
 
     /**
-     * Answers a Collection of the values contained in this HashMap. The
-     * collection is backed by this HashMap so changes to one are reflected by
-     * the other. The collection does not support adding.
+     * Returns a collection of the values contained in this map. The collection
+     * is backed by this map so changes to one are reflected by the other. The
+     * collection supports remove, removeAll, retainAll and clear operations,
+     * and it does not support add or addAll operations.
+     * <p>
+     * This method returns a collection which is the subclass of
+     * AbstractCollection. The iterator method of this subclass returns a
+     * "wrapper object" over the iterator of map's entrySet(). The {@code size}
+     * method wraps the map's size method and the {@code contains} method wraps
+     * the map's containsValue method.
+     * <p>
+     * The collection is created when this method is called for the first time
+     * and returned in response to all subsequent calls. This method may return
+     * different collections when multiple concurrent calls occur, since no
+     * synchronization is performed.
      *
-     * @return a Collection of the values
+     * @return a collection of the values contained in this map.
      */
     @Override
     public Collection<V> values() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java Thu May  7 21:43:41 2009
@@ -23,8 +23,8 @@
 import java.io.Serializable;
 
 /**
- * HashSet is an implementation of Set. All optional operations are supported,
- * adding and removing. The elements can be any objects.
+ * HashSet is an implementation of a Set. All optional operations (adding and
+ * removing) are supported. The elements can be any objects.
  */
 public class HashSet<E> extends AbstractSet<E> implements Set<E>, Cloneable,
         Serializable {
@@ -34,41 +34,41 @@
     transient HashMap<E, HashSet<E>> backingMap;
 
     /**
-     * Constructs a new empty instance of HashSet.
+     * Constructs a new empty instance of {@code HashSet}.
      */
     public HashSet() {
         this(new HashMap<E, HashSet<E>>());
     }
 
     /**
-     * Constructs a new instance of HashSet with the specified capacity.
+     * Constructs a new instance of {@code HashSet} with the specified capacity.
      * 
      * @param capacity
-     *            the initial capacity of this HashSet
+     *            the initial capacity of this {@code HashSet}.
      */
     public HashSet(int capacity) {
         this(new HashMap<E, HashSet<E>>(capacity));
     }
 
     /**
-     * Constructs a new instance of HashSet with the specified capacity and load
-     * factor.
+     * Constructs a new instance of {@code HashSet} with the specified capacity
+     * and load factor.
      * 
      * @param capacity
-     *            the initial capacity
+     *            the initial capacity.
      * @param loadFactor
-     *            the initial load factor
+     *            the initial load factor.
      */
     public HashSet(int capacity, float loadFactor) {
         this(new HashMap<E, HashSet<E>>(capacity, loadFactor));
     }
 
     /**
-     * Constructs a new instance of HashSet containing the unique elements in
-     * the specified collection.
+     * Constructs a new instance of {@code HashSet} containing the unique
+     * elements in the specified collection.
      * 
      * @param collection
-     *            the collection of elements to add
+     *            the collection of elements to add.
      */
     public HashSet(Collection<? extends E> collection) {
         this(new HashMap<E, HashSet<E>>(collection.size() < 6 ? 11 : collection
@@ -83,12 +83,12 @@
     }
 
     /**
-     * Adds the specified object to this HashSet.
+     * Adds the specified object to this {@code HashSet} if not already present.
      * 
      * @param object
-     *            the object to add
-     * @return true when this HashSet did not already contain the object, false
-     *         otherwise
+     *            the object to add.
+     * @return {@code true} when this {@code HashSet} did not already contain
+     *         the object, {@code false} otherwise
      */
     @Override
     public boolean add(E object) {
@@ -96,7 +96,7 @@
     }
 
     /**
-     * Removes all elements from this HashSet, leaving it empty.
+     * Removes all elements from this {@code HashSet}, leaving it empty.
      * 
      * @see #isEmpty
      * @see #size
@@ -107,10 +107,10 @@
     }
 
     /**
-     * Answers a new HashSet with the same elements and size as this HashSet.
-     * 
-     * @return a shallow copy of this HashSet
+     * Returns a new {@code HashSet} with the same elements and size as this
+     * {@code HashSet}.
      * 
+     * @return a shallow copy of this {@code HashSet}.
      * @see java.lang.Cloneable
      */
     @Override
@@ -126,12 +126,12 @@
     }
 
     /**
-     * Searches this HashSet for the specified object.
+     * Searches this {@code HashSet} for the specified object.
      * 
      * @param object
-     *            the object to search for
-     * @return true if <code>object</code> is an element of this HashSet,
-     *         false otherwise
+     *            the object to search for.
+     * @return {@code true} if {@code object} is an element of this
+     *         {@code HashSet}, {@code false} otherwise.
      */
     @Override
     public boolean contains(Object object) {
@@ -139,10 +139,10 @@
     }
 
     /**
-     * Answers if this HashSet has no elements, a size of zero.
-     * 
-     * @return true if this HashSet has no elements, false otherwise
+     * Returns true if this {@code HashSet} has no elements, false otherwise.
      * 
+     * @return {@code true} if this {@code HashSet} has no elements,
+     *         {@code false} otherwise.
      * @see #size
      */
     @Override
@@ -151,10 +151,9 @@
     }
 
     /**
-     * Answers an Iterator on the elements of this HashSet.
-     * 
-     * @return an Iterator on the elements of this HashSet
+     * Returns an Iterator on the elements of this {@code HashSet}.
      * 
+     * @return an Iterator on the elements of this {@code HashSet}.
      * @see Iterator
      */
     @Override
@@ -163,11 +162,11 @@
     }
 
     /**
-     * Removes an occurrence of the specified object from this HashSet.
+     * Removes the specified object from this {@code HashSet}.
      * 
      * @param object
-     *            the object to remove
-     * @return true if this HashSet is modified, false otherwise
+     *            the object to remove.
+     * @return {@code true} if the object was removed, {@code false} otherwise.
      */
     @Override
     public boolean remove(Object object) {
@@ -175,9 +174,9 @@
     }
 
     /**
-     * Answers the number of elements in this HashSet.
+     * Returns the number of elements in this {@code HashSet}.
      * 
-     * @return the number of elements in this HashSet
+     * @return the number of elements in this {@code HashSet}.
      */
     @Override
     public int size() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java Thu May  7 21:43:41 2009
@@ -25,8 +25,8 @@
 import org.apache.harmony.luni.internal.nls.Messages;
 
 /**
- * Hashtable associates keys with values. Keys and values cannot be null. The
- * size of the Hashtable is the number of key/value pairs it contains. The
+ * Hashtable associates keys with values. Both keys and values cannot be null.
+ * The size of the Hashtable is the number of key/value pairs it contains. The
  * capacity is the number of key/value pairs the Hashtable can hold. The load
  * factor is a float value which determines how full the Hashtable gets before
  * expanding the capacity. If the load factor of the Hashtable is exceeded, the
@@ -228,18 +228,19 @@
     }
 
     /**
-     * Constructs a new Hashtable using the default capacity and load factor.
+     * Constructs a new {@code Hashtable} using the default capacity and load
+     * factor.
      */
     public Hashtable() {
         this(11);
     }
 
     /**
-     * Constructs a new Hashtable using the specified capacity and the default
-     * load factor.
+     * Constructs a new {@code Hashtable} using the specified capacity and the
+     * default load factor.
      * 
      * @param capacity
-     *            the initial capacity
+     *            the initial capacity.
      */
     public Hashtable(int capacity) {
         if (capacity >= 0) {
@@ -254,12 +255,13 @@
     }
 
     /**
-     * Constructs a new Hashtable using the specified capacity and load factor.
+     * Constructs a new {@code Hashtable} using the specified capacity and load
+     * factor.
      * 
      * @param capacity
-     *            the initial capacity
+     *            the initial capacity.
      * @param loadFactor
-     *            the initial load factor
+     *            the initial load factor.
      */
     public Hashtable(int capacity, float loadFactor) {
         if (capacity >= 0 && loadFactor > 0) {
@@ -274,11 +276,11 @@
     }
 
     /**
-     * Constructs a new instance of Hashtable containing the mappings from the
-     * specified Map.
+     * Constructs a new instance of {@code Hashtable} containing the mappings
+     * from the specified map.
      * 
      * @param map
-     *            the mappings to add
+     *            the mappings to add.
      */
     public Hashtable(Map<? extends K, ? extends V> map) {
         this(map.size() < 6 ? 11 : (map.size() * 4 / 3) + 11);
@@ -291,8 +293,8 @@
     }
 
     /**
-     * Removes all key/value pairs from this Hashtable, leaving the size zero
-     * and the capacity unchanged.
+     * Removes all key/value pairs from this {@code Hashtable}, leaving the
+     * size zero and the capacity unchanged.
      * 
      * @see #isEmpty
      * @see #size
@@ -304,11 +306,10 @@
     }
 
     /**
-     * Answers a new Hashtable with the same key/value pairs, capacity and load
-     * factor.
-     * 
-     * @return a shallow copy of this Hashtable
+     * Returns a new {@code Hashtable} with the same key/value pairs, capacity
+     * and load factor.
      * 
+     * @return a shallow copy of this {@code Hashtable}.
      * @see java.lang.Cloneable
      */
     @Override
@@ -334,13 +335,13 @@
     }
 
     /**
-     * Answers if this Hashtable contains the specified object as the value of
-     * at least one of the key/value pairs.
+     * Returns true if this {@code Hashtable} contains the specified object as
+     * the value of at least one of the key/value pairs.
      * 
      * @param value
-     *            the object to look for as a value in this Hashtable
-     * @return true if object is a value in this Hashtable, false otherwise
-     * 
+     *            the object to look for as a value in this {@code Hashtable}.
+     * @return {@code true} if object is a value in this {@code Hashtable},
+     *         {@code false} otherwise.
      * @see #containsKey
      * @see java.lang.Object#equals
      */
@@ -362,13 +363,13 @@
     }
 
     /**
-     * Answers if this Hashtable contains the specified object as a key of one
-     * of the key/value pairs.
+     * Returns true if this {@code Hashtable} contains the specified object as a
+     * key of one of the key/value pairs.
      * 
      * @param key
-     *            the object to look for as a key in this Hashtable
-     * @return true if object is a key in this Hashtable, false otherwise
-     * 
+     *            the object to look for as a key in this {@code Hashtable}.
+     * @return {@code true} if object is a key in this {@code Hashtable},
+     *         {@code false} otherwise.
      * @see #contains
      * @see java.lang.Object#equals
      */
@@ -377,24 +378,23 @@
     }
 
     /**
-     * Searches this Hashtable for the specified value.
+     * Searches this {@code Hashtable} for the specified value.
      * 
      * @param value
-     *            the object to search for
-     * @return true if <code>value</code> is a value of this Hashtable, false
-     *         otherwise
+     *            the object to search for.
+     * @return {@code true} if {@code value} is a value of this
+     *         {@code Hashtable}, {@code false} otherwise.
      */
     public boolean containsValue(Object value) {
         return contains(value);
     }
 
     /**
-     * Answers an Enumeration on the values of this Hashtable. The results of
-     * the Enumeration may be affected if the contents of this Hashtable are
-     * modified.
-     * 
-     * @return an Enumeration of the values of this Hashtable
+     * Returns an enumeration on the values of this {@code Hashtable}. The
+     * results of the Enumeration may be affected if the contents of this
+     * {@code Hashtable} are modified.
      * 
+     * @return an enumeration of the values of this {@code Hashtable}.
      * @see #keys
      * @see #size
      * @see Enumeration
@@ -413,11 +413,12 @@
     }
 
     /**
-     * Answers a Set of the mappings contained in this Hashtable. Each element
-     * in the set is a Map.Entry. The set is backed by this Hashtable so changes
-     * to one are reflected by the other. The set does not support adding.
+     * Returns a set of the mappings contained in this {@code Hashtable}. Each
+     * element in the set is a {@link Map.Entry}. The set is backed by this
+     * {@code Hashtable} so changes to one are reflected by the other. The set
+     * does not support adding.
      * 
-     * @return a Set of the mappings
+     * @return a set of the mappings.
      */
     public Set<Map.Entry<K, V>> entrySet() {
         return new Collections.SynchronizedSet<Map.Entry<K, V>>(
@@ -465,15 +466,14 @@
     }
 
     /**
-     * Compares the specified object to this Hashtable and answer if they are
-     * equal. The object must be an instance of Map and contain the same
-     * key/value pairs.
+     * Compares this {@code Hashtable} with the specified object and indicates
+     * if they are equal. In order to be equal, {@code object} must be an
+     * instance of Map and contain the same key/value pairs.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this Map, false
-     *         otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this Map,
+     *         {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -499,13 +499,13 @@
     }
 
     /**
-     * Answers the value associated with the specified key in this Hashtable.
+     * Returns the value associated with the specified key in this
+     * {@code Hashtable}.
      * 
      * @param key
-     *            the key of the value returned
-     * @return the value associated with the specified key, null if the
-     *         specified key does not exist
-     * 
+     *            the key of the value returned.
+     * @return the value associated with the specified key, or {@code null} if
+     *         the specified key does not exist.
      * @see #put
      */
     @Override
@@ -535,14 +535,6 @@
         return null;
     }
 
-    /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
-     * 
-     * @see #equals
-     */
     @Override
     public synchronized int hashCode() {
         int result = 0;
@@ -560,10 +552,10 @@
     }
 
     /**
-     * Answers if this Hashtable has no key/value pairs, a size of zero.
-     * 
-     * @return true if this Hashtable has no key/value pairs, false otherwise
+     * Returns true if this {@code Hashtable} has no key/value pairs.
      * 
+     * @return {@code true} if this {@code Hashtable} has no key/value pairs,
+     *         {@code false} otherwise.
      * @see #size
      */
     @Override
@@ -572,12 +564,11 @@
     }
 
     /**
-     * Answers an Enumeration on the keys of this Hashtable. The results of the
-     * Enumeration may be affected if the contents of this Hashtable are
-     * modified.
-     * 
-     * @return an Enumeration of the keys of this Hashtable
+     * Returns an enumeration on the keys of this {@code Hashtable} instance.
+     * The results of the enumeration may be affected if the contents of this
+     * {@code Hashtable} are modified.
      * 
+     * @return an enumeration of the keys of this {@code Hashtable}.
      * @see #elements
      * @see #size
      * @see Enumeration
@@ -596,11 +587,11 @@
     }
 
     /**
-     * Answers a Set of the keys contained in this Hashtable. The set is backed
-     * by this Hashtable so changes to one are reflected by the other. The set
-     * does not support adding.
+     * Returns a set of the keys contained in this {@code Hashtable}. The set
+     * is backed by this {@code Hashtable} so changes to one are reflected by
+     * the other. The set does not support adding.
      * 
-     * @return a Set of the keys
+     * @return a set of the keys.
      */
     public Set<K> keySet() {
         return new Collections.SynchronizedSet<K>(new AbstractSet<K>() {
@@ -721,17 +712,16 @@
     }
 
     /**
-     * Associate the specified value with the specified key in this Hashtable.
-     * If the key already exists, the old value is replaced. The key and value
-     * cannot be null.
+     * Associate the specified value with the specified key in this
+     * {@code Hashtable}. If the key already exists, the old value is replaced.
+     * The key and value cannot be null.
      * 
      * @param key
-     *            the key to add
+     *            the key to add.
      * @param value
-     *            the value to add
-     * @return the old value associated with the specified key, null if the key
-     *         did not exist
-     * 
+     *            the value to add.
+     * @return the old value associated with the specified key, or {@code null}
+     *         if the key did not exist.
      * @see #elements
      * @see #get
      * @see #keys
@@ -771,10 +761,10 @@
     }
 
     /**
-     * Copies every mapping in the specified Map to this Hashtable.
+     * Copies every mapping to this {@code Hashtable} from the specified map.
      * 
      * @param map
-     *            the Map to copy mappings from
+     *            the map to copy mappings from.
      */
     public synchronized void putAll(Map<? extends K, ? extends V> map) {
         for (Map.Entry<? extends K, ? extends V> entry : map.entrySet()) {
@@ -783,8 +773,8 @@
     }
 
     /**
-     * Increases the capacity of this Hashtable. This method is sent when the
-     * size of this Hashtable exceeds the load factor.
+     * Increases the capacity of this {@code Hashtable}. This method is called
+     * when the size of this {@code Hashtable} exceeds the load factor.
      */
     protected void rehash() {
         int length = (elementData.length << 1) + 1;
@@ -817,13 +807,13 @@
     }
 
     /**
-     * Remove the key/value pair with the specified key from this Hashtable.
+     * Removes the key/value pair with the specified key from this
+     * {@code Hashtable}.
      * 
      * @param key
-     *            the key to remove
-     * @return the value associated with the specified key, null if the
-     *         specified key did not exist
-     * 
+     *            the key to remove.
+     * @return the value associated with the specified key, or {@code null} if
+     *         the specified key did not exist.
      * @see #get
      * @see #put
      */
@@ -853,10 +843,9 @@
     }
 
     /**
-     * Answers the number of key/value pairs in this Hashtable.
-     * 
-     * @return the number of key/value pairs in this Hashtable
+     * Returns the number of key/value pairs in this {@code Hashtable}.
      * 
+     * @return the number of key/value pairs in this {@code Hashtable}.
      * @see #elements
      * @see #keys
      */
@@ -866,9 +855,9 @@
     }
 
     /**
-     * Answers the string representation of this Hashtable.
+     * Returns the string representation of this {@code Hashtable}.
      * 
-     * @return the string representation of this Hashtable
+     * @return the string representation of this {@code Hashtable}.
      */
     @Override
     public synchronized String toString() {
@@ -907,11 +896,11 @@
     }
 
     /**
-     * Answers a Collection of the values contained in this Hashtable. The
-     * collection is backed by this Hashtable so changes to one are reflected by
-     * the other. The collection does not support adding.
+     * Returns a collection of the values contained in this {@code Hashtable}.
+     * The collection is backed by this {@code Hashtable} so changes to one are
+     * reflected by the other. The collection does not support adding.
      * 
-     * @return a Collection of the values
+     * @return a collection of the values.
      */
     public Collection<V> values() {
         return new Collections.SynchronizedCollection<V>(

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java Thu May  7 21:43:41 2009
@@ -23,15 +23,17 @@
 import java.io.Serializable;
 
 /**
- * IdentityHashMap
- * 
- * This is a variant on HashMap which tests equality by reference instead of by
- * value. Basically, keys and values are compared for equality by checking if
- * their references are equal rather than by calling the "equals" function.
- * 
+ * IdentityHashMap is a variant on HashMap which tests equality by reference
+ * instead of equality by value. Basically, keys and values are compared for
+ * equality by checking if their references are equal rather than by calling the
+ * "equals" function.
+ * <p>
+ * <b>Note: This class intentionally violates the general contract of {@code
+ * Map}'s on comparing objects by their {@code equals} method.</b>
+ * <p>
  * IdentityHashMap uses open addressing (linear probing in particular) for
  * collision resolution. This is different from HashMap which uses Chaining.
- * 
+ * <p>
  * Like HashMap, IdentityHashMap is not thread safe, so access by multiple
  * threads must be synchronized by an external mechanism such as
  * Collections.synchronizedMap.
@@ -235,14 +237,14 @@
     }
 
     /**
-     * Create an IdentityHashMap with default maximum size
+     * Creates an IdentityHashMap with default expected maximum size.
      */
     public IdentityHashMap() {
         this(DEFAULT_MAX_SIZE);
     }
 
     /**
-     * Create an IdentityHashMap with the given maximum size parameter
+     * Creates an IdentityHashMap with the specified maximum size parameter.
      * 
      * @param maxSize
      *            The estimated maximum number of entries that will be put in
@@ -280,10 +282,10 @@
     }
 
     /**
-     * Create an IdentityHashMap using the given Map as initial values.
+     * Creates an IdentityHashMap using the given map as initial values.
      * 
      * @param map
-     *            A map of (key,value) pairs to copy into the IdentityHashMap
+     *            A map of (key,value) pairs to copy into the IdentityHashMap.
      */
     public IdentityHashMap(Map<? extends K, ? extends V> map) {
         this(map.size() < 6 ? 11 : map.size() * 2);
@@ -296,13 +298,10 @@
     }
 
     /**
-     * Removes all elements from this Map, leaving it empty.
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Map is not supported
+     * Removes all elements from this map, leaving it empty.
      * 
-     * @see #isEmpty
-     * @see #size
+     * @see #isEmpty()
+     * @see #size()
      */
     @Override
     public void clear() {
@@ -314,11 +313,12 @@
     }
 
     /**
-     * Searches this Map for the specified key.
+     * Returns whether this map contains the specified key.
      * 
      * @param key
-     *            the object to search for
-     * @return true if <code>key</code> is a key of this Map, false otherwise
+     *            the key to search for.
+     * @return {@code true} if this map contains the specified key,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean containsKey(Object key) {
@@ -331,13 +331,12 @@
     }
 
     /**
-     * Searches this Map for the specified value.
-     * 
+     * Returns whether this map contains the specified value.
      * 
      * @param value
-     *            the object to search for
-     * @return true if <code>value</code> is a value of this Map, false
-     *         otherwise
+     *            the value to search for.
+     * @return {@code true} if this map contains the specified value,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean containsValue(Object value) {
@@ -354,11 +353,11 @@
     }
 
     /**
-     * Answers the value of the mapping with the specified key.
+     * Returns the value of the mapping with the specified key.
      * 
      * @param key
-     *            the key
-     * @return the value of the mapping with the specified key
+     *            the key.
+     * @return the value of the mapping with the specified key.
      */
     @Override
     public V get(Object key) {
@@ -437,11 +436,11 @@
      * Maps the specified key to the specified value.
      * 
      * @param key
-     *            the key
+     *            the key.
      * @param value
-     *            the value
-     * @return the value of any previous mapping with the specified key or null
-     *         if there was no mapping
+     *            the value.
+     * @return the value of any previous mapping with the specified key or
+     *         {@code null} if there was no such mapping.
      */
     @Override
     public V put(K key, V value) {
@@ -478,14 +477,14 @@
     }
     
     /**
-     * Copies all the mappings in the given map to this map. These mappings will
-     * replace all mappings that this map had for any of the keys currently in
-     * the given map.
+     * Copies all the mappings in the specified map to this map. These mappings
+     * will replace all mappings that this map had for any of the keys currently
+     * in the given map.
      * 
      * @param map
-     *            the Map to copy mappings from
+     *            the map to copy mappings from.
      * @throws NullPointerException
-     *             if the given map is null
+     *             if {@code map} is {@code null}.
      */
     @Override
     public void putAll(Map<? extends K, ? extends V> map) {
@@ -516,12 +515,12 @@
     }
 
     /**
-     * Removes a mapping with the specified key from this IdentityHashMap.
+     * Removes the mapping with the specified key from this map.
      * 
      * @param key
-     *            the key of the mapping to remove
-     * @return the value of the removed mapping, or null if key is not a key in
-     *         this Map
+     *            the key of the mapping to remove.
+     * @return the value of the removed mapping, or {@code null} if no mapping
+     *         for the specified key was found.
      */
     @Override
     public V remove(Object key) {
@@ -576,12 +575,11 @@
     }
 
     /**
-     * Answers a Set of the mappings contained in this IdentityHashMap. Each
-     * element in the set is a Map.Entry. The set is backed by this Map so
-     * changes to one are reflected by the other. The set does not support
-     * adding.
+     * Returns a set containing all of the mappings in this map. Each mapping is
+     * an instance of {@link Map.Entry}. As the set is backed by this map,
+     * changes in one will be reflected in the other.
      * 
-     * @return a Set of the mappings
+     * @return a set of the mappings.
      */
     @Override
     public Set<Map.Entry<K, V>> entrySet() {
@@ -589,11 +587,11 @@
     }
 
     /**
-     * Answers a Set of the keys contained in this IdentityHashMap. The set is
-     * backed by this IdentityHashMap so changes to one are reflected by the
-     * other. The set does not support adding.
+     * Returns a set of the keys contained in this map. The set is backed by
+     * this map so changes to one are reflected by the other. The set does not
+     * support adding.
      * 
-     * @return a Set of the keys
+     * @return a set of the keys.
      */
     @Override
     public Set<K> keySet() {
@@ -638,11 +636,23 @@
     }
 
     /**
-     * Answers a Collection of the values contained in this IdentityHashMap. The
-     * collection is backed by this IdentityHashMap so changes to one are
-     * reflected by the other. The collection does not support adding.
+     * Returns a collection of the values contained in this map. The collection
+     * is backed by this map so changes to one are reflected by the other. The
+     * collection supports remove, removeAll, retainAll and clear operations,
+     * and it does not support add or addAll operations.
+     * <p>
+     * This method returns a collection which is the subclass of
+     * AbstractCollection. The iterator method of this subclass returns a
+     * "wrapper object" over the iterator of map's entrySet(). The {@code size}
+     * method wraps the map's size method and the {@code contains} method wraps
+     * the map's containsValue method.
+     * <p>
+     * The collection is created when this method is called for the first time
+     * and returned in response to all subsequent calls. This method may return
+     * different collections when multiple concurrent calls occur, since no
+     * synchronization is performed.
      * 
-     * @return a Collection of the values
+     * @return a collection of the values contained in this map.
      */
     @Override
     public Collection<V> values() {
@@ -692,13 +702,14 @@
     /**
      * Compares this map with other objects. This map is equal to another map is
      * it represents the same set of mappings. With this map, two mappings are
-     * the same if both the key and the value are equal by reference.
-     * 
-     * When compared with a map that is not an IdentityHashMap, the equals
-     * method is not necessarily symmetric (a.equals(b) implies b.equals(a)) nor
+     * the same if both the key and the value are equal by reference. When
+     * compared with a map that is not an IdentityHashMap, the equals method is
+     * neither necessarily symmetric (a.equals(b) implies b.equals(a)) nor
      * transitive (a.equals(b) and b.equals(c) implies a.equals(c)).
      * 
-     * @return whether the argument object is equal to this object
+     * @param object
+     *            the object to compare to.
+     * @return whether the argument object is equal to this object.
      */
     @Override
     public boolean equals(Object object) {
@@ -728,11 +739,10 @@
     }
 
     /**
-     * Answers a new IdentityHashMap with the same mappings and size as this
+     * Returns a new IdentityHashMap with the same mappings and size as this
      * one.
      * 
-     * @return a shallow copy of this IdentityHashMap
-     * 
+     * @return a shallow copy of this IdentityHashMap.
      * @see java.lang.Cloneable
      */
     @Override
@@ -745,11 +755,11 @@
     }
 
     /**
-     * Answers if this IdentityHashMap has no elements, a size of zero.
-     * 
-     * @return true if this IdentityHashMap has no elements, false otherwise
+     * Returns whether this IdentityHashMap has no elements.
      * 
-     * @see #size
+     * @return {@code true} if this IdentityHashMap has no elements,
+     *         {@code false} otherwise.
+     * @see #size()
      */
     @Override
     public boolean isEmpty() {
@@ -757,9 +767,9 @@
     }
 
     /**
-     * Answers the number of mappings in this IdentityHashMap.
+     * Returns the number of mappings in this IdentityHashMap.
      * 
-     * @return the number of mappings in this IdentityHashMap
+     * @return the number of mappings in this IdentityHashMap.
      */
     @Override
     public int size() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java Thu May  7 21:43:41 2009
@@ -19,41 +19,42 @@
 import java.io.Serializable;
 
 /**
- * The unchecked exception will be thrown out if an invalid Unicode code point,
- * which is Character.isValidCodePoint(int), is passed as a parameter to
- * Formatter.
+ * An {@code IllegalFormatCodePointException} will be thrown if an invalid
+ * Unicode code point (defined by {@link Character#isValidCodePoint(int)}) is
+ * passed as a parameter to a Formatter.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class IllegalFormatCodePointException extends IllegalFormatException
         implements Serializable {
-
     private static final long serialVersionUID = 19080630L;
 
     private int c;
 
     /**
-     * Constructs an IllegalFormatCodePointException which is specified by the
-     * invalid Unicode code point.
+     * Constructs a new {@code IllegalFormatCodePointException} which is
+     * specified by the invalid Unicode code point.
      * 
      * @param c
-     *            The invalid Unicode code point.
+     *           the invalid Unicode code point.
      */
     public IllegalFormatCodePointException(int c) {
         this.c = c;
     }
 
     /**
-     * Return the invalid Unicode code point.
+     * Returns the invalid Unicode code point.
      * 
-     * @return The invalid Unicode code point.
+     * @return the invalid Unicode code point.
      */
     public int getCodePoint() {
         return c;
     }
 
     /**
-     * Return the message string of the IllegalFormatCodePointException.
+     * Returns the message string of the IllegalFormatCodePointException.
      * 
-     * @return The message string of the IllegalFormatCodePointException.
+     * @return the message string of the IllegalFormatCodePointException.
      */
     @Override
     public String getMessage() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java Thu May  7 21:43:41 2009
@@ -19,14 +19,15 @@
 import java.io.Serializable;
 
 /**
- * The unchecked exception will be thrown out when the parameter is incompatible
- * with the corresponding format specifier.
+ * An {@code IllegalFormatConversionException} will be thrown when the parameter
+ * is incompatible with the corresponding format specifier.
  * 
+ * @see java.lang.RuntimeException
+ *
  * @since 1.5
  */
 public class IllegalFormatConversionException extends IllegalFormatException
         implements Serializable {
-
     private static final long serialVersionUID = 17000126L;
 
     private char c;
@@ -34,13 +35,13 @@
     private Class<?> arg;
 
     /**
-     * Constructs an IllegalFormatConversionException with the class of the
-     * mismatched conversion and corresponding parameter.
+     * Constructs a new {@code IllegalFormatConversionException} with the class
+     * of the mismatched conversion and corresponding parameter.
      * 
      * @param c
-     *            The class of the mismatched conversion.
+     *           the class of the mismatched conversion.
      * @param arg
-     *            The corresponding parameter.
+     *           the corresponding parameter.
      */
     public IllegalFormatConversionException(char c, Class<?> arg) {
         this.c = c;
@@ -51,27 +52,27 @@
     }
 
     /**
-     * Return the class of the mismatched parameter.
+     * Returns the class of the mismatched parameter.
      * 
-     * @return The class of the mismatched parameter.
+     * @return the class of the mismatched parameter.
      */
     public Class<?> getArgumentClass() {
         return arg;
     }
 
     /**
-     * Return the incompatible conversion.
+     * Returns the incompatible conversion.
      * 
-     * @return The incompatible conversion.
+     * @return the incompatible conversion.
      */
     public char getConversion() {
         return c;
     }
 
     /**
-     * Return the message string of the IllegalFormatConversionException.
+     * Returns the message string of the IllegalFormatConversionException.
      * 
-     * @return The message string of the IllegalFormatConversionException.
+     * @return the message string of the IllegalFormatConversionException.
      */
     @Override
     public String getMessage() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java Thu May  7 21:43:41 2009
@@ -18,10 +18,12 @@
 import java.io.Serializable;
 
 /**
- * Unchecked Exception that is to be thrown out when a format string that
+ * An {@code IllegalFormatException} is thrown when a format string that
  * contains either an illegal syntax or format specifier is transferred as a
- * parameter. Only a subclass that is inherited explicitly from this exception
- * is allowed to be instantiated.
+ * parameter. Only subclasses inheriting explicitly from this exception are
+ * allowed to be instantiated.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class IllegalFormatException extends IllegalArgumentException implements
         Serializable {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java Thu May  7 21:43:41 2009
@@ -19,21 +19,23 @@
 import java.io.Serializable;
 
 /**
- * The unchecked exception will be thrown out if the combination of the format
- * flags is illegal.
+ * An {@code IllegalFormatFlagsException} will be thrown if the combination of
+ * the format flags is illegal.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class IllegalFormatFlagsException extends IllegalFormatException
         implements Serializable {
-
     private static final long serialVersionUID = 790824L;
 
     private String flags;
 
     /**
-     * Constructs an IllegalFormatFlagsException with the specified flags.
+     * Constructs a new {@code IllegalFormatFlagsException} with the specified
+     * flags.
      * 
      * @param f
-     *            The specified flags.
+     *           the specified flags.
      */
     public IllegalFormatFlagsException(String f) {
         if (null == f) {
@@ -43,18 +45,18 @@
     }
 
     /**
-     * Return the flags that are illegal.
+     * Returns the flags that are illegal.
      * 
-     * @return The flags that are illegal.
+     * @return the flags that are illegal.
      */
     public String getFlags() {
         return flags;
     }
 
     /**
-     * Return the message string of the IllegalFormatFlagsException.
+     * Returns the message string of the IllegalFormatFlagsException.
      * 
-     * @return The message string of the IllegalFormatFlagsException.
+     * @return the message string of the IllegalFormatFlagsException.
      */
     @Override
     public String getMessage() {
@@ -64,4 +66,5 @@
         buffer.append("'");
         return buffer.toString();
     }
+
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java Thu May  7 21:43:41 2009
@@ -17,21 +17,23 @@
 package java.util;
 
 /**
- * The unchecked exception will be thrown out when the precision is a negative
- * other than -1, or the conversion does not support a precision or other cases
- * when the precision is not supported.
+ * An {@code IllegalFormatPrecisionException} will be thrown if the precision is
+ * a negative other than -1 or in other cases where precision is not supported.
+ * 
+ * @see java.lang.RuntimeException
  */
-public class IllegalFormatPrecisionException extends IllegalFormatException {
 
+public class IllegalFormatPrecisionException extends IllegalFormatException {
     private static final long serialVersionUID = 18711008L;
 
     private int p;
 
     /**
-     * Constructs a IllegalFormatPrecisionException with specified precision.
+     * Constructs a new {@code IllegalFormatPrecisionException} with specified
+     * precision.
      * 
      * @param p
-     *            The precision.
+     *           the precision.
      */
     public IllegalFormatPrecisionException(int p) {
         this.p = p;
@@ -49,7 +51,7 @@
     /**
      * Returns the message of the exception.
      * 
-     * @return The message of the exception.
+     * @return the message of the exception.
      */
     @Override
     public String getMessage() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java Thu May  7 21:43:41 2009
@@ -17,9 +17,11 @@
 package java.util;
 
 /**
- * The unchecked exception will be thrown out when the width is a negative other
- * than -1, or the conversion does not support a width or other cases when the
- * width is not supported.
+ * An {@code IllegalFormatWidthException} will be thrown if the width is a
+ * negative value other than -1 or in other cases where a width is not
+ * supported.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class IllegalFormatWidthException extends IllegalFormatException {
 
@@ -28,10 +30,11 @@
     private int w;
 
     /**
-     * Constructs a IllegalFormatWidthException with specified width.
+     * Constructs a new {@code IllegalFormatWidthException} with specified
+     * width.
      * 
      * @param w
-     *            The width.
+     *           the width.
      */
     public IllegalFormatWidthException(int w) {
         this.w = w;
@@ -49,7 +52,7 @@
     /**
      * Returns the message of the exception.
      * 
-     * @return The message of the exception.
+     * @return the message of the exception.
      */
     @Override
     public String getMessage() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java Thu May  7 21:43:41 2009
@@ -18,10 +18,12 @@
 import java.io.Serializable;
 
 /**
- * An InputMismatchException is thrown by a scanner to indicate that the next
- * token does not match the pattern the specified type.
+ * An {@code InputMismatchException} is thrown by a scanner to indicate that the
+ * next token does not match or is out of range for the type specified in the
+ * pattern.
  * 
  * @see Scanner
+ * @see java.lang.RuntimeException
  */
 public class InputMismatchException extends NoSuchElementException implements
         Serializable {
@@ -29,18 +31,19 @@
     private static final long serialVersionUID = 8811230760997066428L;
 
     /**
-     * Constructs a InputMismatchException with no error message
-     * 
+     * Constructs a new {@code InputMismatchException} with the current stack
+     * trace filled in.
      */
     public InputMismatchException() {
         super();
     }
 
     /**
-     * Constructs a InputMismatchException with msg as its error message
+     * Constructs a new {@code InputMismatchException} with the stack trace
+     * filled in and {@code msg} as its error message.
      * 
      * @param msg
-     *            The specified error message
+     *           the specified error message.
      */
     public InputMismatchException(String msg) {
         super(msg);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java Thu May  7 21:43:41 2009
@@ -22,14 +22,37 @@
 import java.io.ObjectOutputStream;
 import java.io.IOException;
 
+/**
+ * An {@code InvalidPropertiesFormatException} is thrown if loading the XML
+ * document defining the properties does not follow the {@code Properties}
+ * specification.
+ * 
+ * Even though this Exception inherits the {@code Serializable} interface, it is not
+ * serializable. The methods used for serialization throw
+ * {@code NotSerializableException}s.
+ */
 public class InvalidPropertiesFormatException extends IOException {
     
     private static final long serialVersionUID = 7763056076009360219L;
-    
+
+    /**
+     * Constructs a new {@code InvalidPropertiesFormatException} with the
+     * current stack trace and message filled in.
+     * 
+     * @param m
+     *           the detail message for the exception.
+     */
     public InvalidPropertiesFormatException(String m) {
         super(m);
     }
 
+    /**
+     * Constructs a new {@code InvalidPropertiesFormatException} with the cause
+     * for the Exception.
+     * 
+     * @param c
+     *           the cause for the Exception.
+     */
     public InvalidPropertiesFormatException(Throwable c) {
         initCause(c);
     }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java Thu May  7 21:43:41 2009
@@ -17,42 +17,47 @@
 
 package java.util;
 
+
 /**
- * An Iterator is used to sequence over a collection of objects.
+ * An Iterator is used to sequence over a collection of objects. Conceptual, an
+ * iterator is always positioned between two elements of a collection. A fresh
+ * iterator is always positioned in front of the first element.
+ * 
+ * If a collection has been changed since its creation, methods {@code next} and
+ * {@code hasNext()} may throw a {@code ConcurrentModificationException}.
+ * Iterators with this behavior are called fail-fast iterators.
  */
 public interface Iterator<E> {
     /**
-     * Answers if there are more elements to iterate.
-     * 
-     * @return true if there are more elements, false otherwise
+     * Returns whether there are more elements to iterate, i.e. whether the
+     * iterator is positioned in front of an element.
      * 
+     * @return {@code true} if there are more elements, {@code false} otherwise.
      * @see #next
      */
     public boolean hasNext();
 
     /**
-     * Answers the next object in the iteration.
-     * 
-     * @return the next object
-     * 
-     * @exception NoSuchElementException
-     *                when there are no more elements
+     * Returns the next object in the iteration, i.e. returns the element in
+     * front of the iterator and advances the iterator by one position.
      * 
+     * @return the next object.
+     * @throws NoSuchElementException
+     *             if there are no more elements.
      * @see #hasNext
      */
     public E next();
 
     /**
-     * Removes the last object returned by <code>next</code> from the
-     * collection.
+     * Removes the last object returned by {@code next} from the collection.
+     * This method can only be called once after {@code next} was called.
      * 
-     * @exception UnsupportedOperationException
-     *                when removing is not supported by the collection being
-     *                iterated
-     * @exception IllegalStateException
-     *                when <code>next</code> has not been called, or
-     *                <code>remove</code> has already been called after the
-     *                last call to <code>next</code>
+     * @throws UnsupportedOperationException
+     *             if removing is not supported by the collection being
+     *             iterated.
+     * @throws IllegalStateException
+     *             if {@code next} has not been called, or {@code remove} has
+     *             already been called after the last call to {@code next}.
      */
     public void remove();
 }



Mime
View raw message