harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [5/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/EnumMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumMap.java Thu May  7 21:43:41 2009
@@ -22,6 +22,9 @@
 import java.io.Serializable;
 import java.lang.reflect.Array;
 
+/**
+ * An {@code Map} specialized for use with {@code Enum} types as keys.
+ */
 public class EnumMap<K extends Enum<K>, V> extends AbstractMap<K, V> implements
         Serializable, Cloneable {
 
@@ -379,44 +382,43 @@
     }
 
     /**
-     * Constructs an empty EnumMap.
-     * 
+     * Constructs an empty {@code EnumMap} using the given key type.
+     *
      * @param keyType
-     *           the Class that is to be used for the key type for this map
+     *            the class object giving the type of the keys used by this {@code EnumMap}.
      * @throws NullPointerException
-     *             if the keyType is null
+     *             if {@code keyType} is {@code null}.
      */
     public EnumMap(Class<K> keyType) {
         initialization(keyType);
     }
 
     /**
-     * Constructs an EnumMap using the same key type and contents as the given
-     * EnumMap.
-     * 
+     * Constructs an {@code EnumMap} using the same key type as the given {@code EnumMap} and
+     * initially containing the same mappings.
+     *
      * @param map
-     *            the EnumMap from which the initial contents of this EnumMap
-     *            are copied
+     *            the {@code EnumMap} from which this {@code EnumMap} is initialized.
      * @throws NullPointerException
-     *             if the map is null
+     *             if {@code map} is {@code null}.
      */
     public EnumMap(EnumMap<K, ? extends V> map) {
         initialization(map);
     }
 
     /**
-     * Constructs an EnumMap with the same contents as the given Map. If the Map
-     * is an EnumMap, this is equivalent to calling
-     * {@link EnumMap#EnumMap(EnumMap)}}. Otherwise, the given map cannot be
-     * empty so that the key type of this EnumMap can be inferred.
+     * Constructs an {@code EnumMap} initialized from the given map. If the given map
+     * is an {@code EnumMap} instance, this constructor behaves in the exactly the same
+     * way as {@link EnumMap#EnumMap(EnumMap)}}. Otherwise, the given map
+     * should contain at least one mapping.
      * 
      * @param map
-     *            the Map from which the initial contents of this EnumMap are
-     *            copied
+     *            the map from which this {@code EnumMap} is initialized.
      * @throws IllegalArgumentException
-     *             if the map is empty and is not of type <code>EnumMap</code>
+     *             if {@code map} is not an {@code EnumMap} instance and does not contain
+     *             any mappings.
      * @throws NullPointerException
-     *             if the map is null
+     *             if {@code map} is {@code null}.
      */
     @SuppressWarnings("unchecked")
     public EnumMap(Map<K, ? extends V> map) {
@@ -439,7 +441,10 @@
     }
 
     /**
-     * Clears this map.
+     * Removes all elements from this {@code EnumMap}, leaving it empty.
+     *
+     * @see #isEmpty()
+     * @see #size()
      */
     @Override
     public void clear() {
@@ -449,9 +454,9 @@
     }
 
     /**
-     * Clones this map to create a shallow copy.
+     * Returns a shallow copy of this {@code EnumMap}.
      * 
-     * @return a shallow copy of this map
+     * @return a shallow copy of this {@code EnumMap}.
      */
     @SuppressWarnings("unchecked")
     @Override
@@ -466,11 +471,12 @@
     }
 
     /**
-     * Returns true if the given object is present as a key in this map.
+     * Returns whether this {@code EnumMap} contains the specified key.
      * 
      * @param key
-     *            the key to look for
-     * @return true if this map contains the key
+     *            the key to search for.
+     * @return {@code true} if this {@code EnumMap} contains the specified key,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean containsKey(Object key) {
@@ -482,11 +488,12 @@
     }
 
     /**
-     * Returns true if the given object is present as a value in this map.
+     * Returns whether this {@code EnumMap} contains the specified value.
      * 
      * @param value
-     *            the value to look for
-     * @return true if this map contains the value.
+     *            the value to search for.
+     * @return {@code true} if this {@code EnumMap} contains the specified value,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean containsValue(Object value) {
@@ -507,16 +514,14 @@
     }
 
     /**
-     * Returns a Set of <code>Map.Entry</code>s that represent the entries in
-     * this EnumMap. Making changes to this Set will change the original EnumMap
-     * and vice-versa. Entries can be removed from the Set, or their values can
-     * be changed, but new entries cannot be added.
-     * 
-     * The order of the entries in the Set will be the order that the Enum keys
+     * Returns a {@code Set} containing all of the mappings in this {@code EnumMap}. Each mapping is
+     * an instance of {@link Map.Entry}. As the {@code Set} is backed by this {@code EnumMap},
+     * changes in one will be reflected in the other.
+     * <p>
+     * The order of the entries in the set will be the order that the enum keys
      * were declared in.
-     * 
-     * @return a Set of <code>Map.Entry</code>s representing the entries in
-     *         this EnumMap
+     *
+     * @return a {@code Set} of the mappings.
      */
     @Override
     public Set<Map.Entry<K, V>> entrySet() {
@@ -527,11 +532,15 @@
     }
 
     /**
-     * Returns true if this EnumMap is equal to the given object.
+     * Compares the argument to the receiver, and returns {@code true} if the
+     * specified {@code Object} is an {@code EnumMap} and both {@code EnumMap}s contain the same mappings.
      * 
      * @param object
-     *            the object
-     * @return true if this EnumMap is equal to the given object.
+     *            the {@code Object} to compare with this {@code EnumMap}.
+     * @return boolean {@code true} if {@code object} is the same as this {@code EnumMap},
+     *         {@code false} otherwise.
+     * @see #hashCode()
+     * @see #entrySet()
      */
     @SuppressWarnings("unchecked")
     @Override
@@ -551,12 +560,12 @@
     }
 
     /**
-     * Returns the value stored in this map for the given key in this map, or null
-     * if this map has no entry for that key.
+     * Returns the value of the mapping with the specified key.
      * 
      * @param key
-     *            the key to get the value for.
-     * @return the value for the given 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
     @SuppressWarnings("unchecked")
@@ -569,14 +578,14 @@
     }
 
     /**
-     * Returns a Set containing the keys for this EnumMap. Making changes to
-     * this Set will change the original EnumMap and vice-versa. Entries can be
-     * removed from the Set, but new entries cannot be added.
-     * 
-     * The order of the Set will be the order that the Enum keys were declared
+     * Returns a set of the keys contained in this {@code EnumMap}. The {@code Set} is backed by
+     * this {@code EnumMap} so changes to one are reflected in the other. The {@code Set} does not
+     * support adding.
+     * <p>
+     * The order of the set will be the order that the enum keys were declared
      * in.
      * 
-     * @return a Set containing the keys for this EnumMap.
+     * @return a {@code Set} of the keys.
      */
     @Override
     public Set<K> keySet() {
@@ -587,17 +596,24 @@
     }
 
     /**
-     * Stores a value in this map for the given key. If the map already has an
-     * entry for this key the current value will be overwritten.
+     * Maps the specified key to the specified value.
      * 
      * @param key
-     *            the key
+     *            the key.
      * @param value
-     *            the value to store for the given key
-     * @return the value stored for the given key, or null if this map has no
-     *         entry for the key
+     *            the value.
+     * @return the value of any previous mapping with the specified key or
+     *         {@code null} if there was no mapping.
+     * @throws UnsupportedOperationException
+     *                if adding to this map is not supported.
+     * @throws ClassCastException
+     *                if the class of the key or value is inappropriate for this
+     *                map.
+     * @throws IllegalArgumentException
+     *                if the key or value cannot be added to this map.
      * @throws NullPointerException
-     *             if the key is null
+     *                if the key or value is {@code null} and this {@code EnumMap} does not
+     *                support {@code null} keys or values.
      */
     @Override
     @SuppressWarnings("unchecked")
@@ -606,12 +622,20 @@
     }
 
     /**
-     * Add all the entries in the given map to this map
+     * Copies every mapping in the specified {@code Map} to this {@code EnumMap}.
      * 
      * @param map
-     *            the map whose entries to copy
+     *            the {@code Map} to copy mappings from.
+     * @throws UnsupportedOperationException
+     *                if adding to this {@code EnumMap} is not supported.
+     * @throws ClassCastException
+     *                if the class of a key or value is inappropriate for this
+     *                {@code EnumMap}.
+     * @throws IllegalArgumentException
+     *                if a key or value cannot be added to this map.
      * @throws NullPointerException
-     *             if the given map or any of its keys are null
+     *                if a key or value is {@code null} and this {@code EnumMap} does not
+     *                support {@code null} keys or values.
      */
     @Override
     @SuppressWarnings("unchecked")
@@ -620,12 +644,14 @@
     }
 
     /**
-     * Removes the entry for the given key from this map, if there is one.
+     * Removes a mapping with the specified key from this {@code EnumMap}.
      * 
      * @param key
-     *            the key to remove
-     * @return the value that had been stored for the key, or null if there was
-     *         not one.
+     *            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.
+     * @throws UnsupportedOperationException
+     *                if removing from this {@code EnumMap} is not supported.
      */
     @Override
     @SuppressWarnings("unchecked")
@@ -644,9 +670,9 @@
     }
 
     /**
-     * Returns the size of this map
+     * Returns the number of elements in this {@code EnumMap}.
      * 
-     * @return the number of entries in the map
+     * @return the number of elements in this {@code EnumMap}.
      */
     @Override
     public int size() {
@@ -654,15 +680,16 @@
     }
 
     /**
-     * Returns a Collection containing the values for this EnumMap. Making
-     * changes to this Collection will change the original EnumMap and
-     * vice-versa. Values can be removed from the Collection, but new entries
-     * cannot be added.
-     * 
-     * The order of the values in the Collection will be the order that their
-     * corresponding Enum keys were declared in.
+     * Returns a {@code Collection} of the values contained in this {@code EnumMap}. The returned
+     * {@code Collection} complies with the general rule specified in
+     * {@link Map#values()}. The {@code Collection}'s {@code Iterator} will return the values
+     * in the their corresponding keys' natural order (the {@code Enum} constants are
+     * declared in this order).
+     * <p>
+     * The order of the values in the collection will be the order that their
+     * corresponding enum keys were declared in.
      * 
-     * @return a Collection containing the values for this EnumMap
+     * @return a collection of the values contained in this {@code EnumMap}.
      */
     @Override
     public Collection<V> values() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EnumSet.java Thu May  7 21:43:41 2009
@@ -17,6 +17,9 @@
 
 import java.io.Serializable;
 
+/**
+ * An EnumSet is a specialized Set to be used with enums as keys.
+ */
 public abstract class EnumSet<E extends Enum<E>> extends AbstractSet<E>
         implements Cloneable, Serializable {
 
@@ -29,14 +32,15 @@
     }
 
     /**
-     * Creates an empty enum set. The permitted elements are of type Class<E>.
+     * Creates an empty enum set. The permitted elements are of type
+     * Class&lt;E&gt;.
      * 
      * @param elementType
-     *            the class object for the elements contained
-     * @return an empty enum set, with permitted elements of the specified
-     *         elementType
-     * @throws NullPointerException
-     *             if the specified elementType is null
+     *            the class object for the elements contained.
+     * @return an empty enum set, with permitted elements of type {@code
+     *         elementType}.
+     * @throws ClassCastException
+     *             if the specified element type is not and enum type.
      */
     public static <E extends Enum<E>> EnumSet<E> noneOf(Class<E> elementType) {
         if (!elementType.isEnum()) {
@@ -49,14 +53,14 @@
     }
 
     /**
-     * Creates an enum set. Element is contained in this enum set if and only if
-     * it is a member of the specified element type.
+     * Creates an enum set filled with all the enum elements of the specified
+     * {@code elementType}.
      * 
      * @param elementType
-     *            the class object for the elements contained
-     * @return an enum set with elements solely from the specified element type
-     * @throws NullPointerException
-     *             if the specified elementType is null
+     *            the class object for the elements contained.
+     * @return an enum set with elements solely from the specified element type.
+     * @throws ClassCastException
+     *             if the specified element type is not and enum type.
      */
     public static <E extends Enum<E>> EnumSet<E> allOf(Class<E> elementType) {
         EnumSet<E> set = noneOf(elementType);
@@ -65,14 +69,15 @@
     }
 
     /**
-     * Creates an enum set. All the contained elements are of type Class<E>,
-     * and the contained elements are the same as those contained in s.
+     * Creates an enum set. All the contained elements are of type
+     * Class&lt;E&gt;, and the contained elements are the same as those
+     * contained in {@code s}.
      * 
      * @param s
-     *            the enum set from which to copy
-     * @return an enum set with all the elements from the specified enum set
-     * @throws NullPointerException
-     *             if the specified enum set is null
+     *            the enum set from which to copy.
+     * @return an enum set with all the elements from the specified enum set.
+     * @throws ClassCastException
+     *             if the specified element type is not and enum type.
      */
     public static <E extends Enum<E>> EnumSet<E> copyOf(EnumSet<E> s) {
         EnumSet<E> set = EnumSet.noneOf(s.elementClass);
@@ -82,16 +87,17 @@
 
     /**
      * Creates an enum set. The contained elements are the same as those
-     * contained in collection c. If c is an enum set, invoking this method is
-     * the same as invoking {@link #copyOf(EnumSet)}.
+     * contained in collection {@code c}. If c is an enum set, invoking this
+     * method is the same as invoking {@link #copyOf(EnumSet)}.
      * 
      * @param c
-     *            the collection from which to copy
-     * @return an enum set with all the elements from the specified collection
+     *            the collection from which to copy. if it is not an enum set,
+     *            it must not be empty.
+     * @return an enum set with all the elements from the specified collection.
      * @throws IllegalArgumentException
-     *             if c is not an enum set and contains no elements at all
+     *             if c is not an enum set and contains no elements at all.
      * @throws NullPointerException
-     *             if the specified collection is null
+     *             if {@code c} is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> copyOf(Collection<E> c) {
         if (c instanceof EnumSet) {
@@ -115,11 +121,11 @@
      * specified enum set.
      * 
      * @param s
-     *            the specified enum set
-     * @return an enum set with all the elements complement those from the
-     *         specified enum set
+     *            the specified enum set.
+     * @return an enum set with all the elements complementary to those from the
+     *         specified enum set.
      * @throws NullPointerException
-     *             if the specified enum set is null
+     *             if {@code s} is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> complementOf(EnumSet<E> s) {
         EnumSet<E> set = EnumSet.noneOf(s.elementClass);
@@ -133,14 +139,14 @@
     /**
      * Creates a new enum set, containing only the specified element. There are
      * six overloadings of the method. They accept from one to five elements
-     * respectively. The sixth one receives arbitrary number of elements, and
-     * runs slower than those only receive fixed number of elements.
+     * respectively. The sixth one receives an arbitrary number of elements, and
+     * runs slower than those that only receive a fixed number of elements.
      * 
      * @param e
-     *            the initially contained element
-     * @return an enum set containing the specified element
+     *            the element to be initially contained.
+     * @return an enum set containing the specified element.
      * @throws NullPointerException
-     *             if the specified element is null
+     *             if {@code e} is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> of(E e) {
         EnumSet<E> set = EnumSet.noneOf(e.getDeclaringClass());
@@ -151,16 +157,16 @@
     /**
      * Creates a new enum set, containing only the specified elements. There are
      * six overloadings of the method. They accept from one to five elements
-     * respectively. The sixth one receives arbitrary number of elements, and
-     * runs slower than those only receive fixed number of elements.
+     * respectively. The sixth one receives an arbitrary number of elements, and
+     * runs slower than those that only receive a fixed number of elements.
      * 
      * @param e1
-     *            the initially contained element
+     *            the initially contained element.
      * @param e2
-     *            another initially contained element
-     * @return an enum set containing the specified elements
+     *            another initially contained element.
+     * @return an enum set containing the specified elements.
      * @throws NullPointerException
-     *             if any of the specified elements is null
+     *             if any of the specified elements is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2) {
         EnumSet<E> set = of(e1);
@@ -171,18 +177,18 @@
     /**
      * Creates a new enum set, containing only the specified elements. There are
      * six overloadings of the method. They accept from one to five elements
-     * respectively. The sixth one receives arbitrary number of elements, and
-     * runs slower than those only receive fixed number of elements.
+     * respectively. The sixth one receives an arbitrary number of elements, and
+     * runs slower than those that only receive a fixed number of elements.
      * 
      * @param e1
-     *            the initially contained element
+     *            the initially contained element.
      * @param e2
-     *            another initially contained element
+     *            another initially contained element.
      * @param e3
-     *            another initially contained element
-     * @return an enum set containing the specified elements
+     *            another initially contained element.
+     * @return an enum set containing the specified elements.
      * @throws NullPointerException
-     *             if any of the specified elements is null
+     *             if any of the specified elements is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3) {
         EnumSet<E> set = of(e1, e2);
@@ -193,20 +199,20 @@
     /**
      * Creates a new enum set, containing only the specified elements. There are
      * six overloadings of the method. They accept from one to five elements
-     * respectively. The sixth one receives arbitrary number of elements, and
-     * runs slower than those only receive fixed number of elements.
+     * respectively. The sixth one receives an arbitrary number of elements, and
+     * runs slower than those that only receive a fixed number of elements.
      * 
      * @param e1
-     *            the initially contained element
+     *            the initially contained element.
      * @param e2
-     *            another initially contained element
+     *            another initially contained element.
      * @param e3
-     *            another initially contained element
+     *            another initially contained element.
      * @param e4
-     *            another initially contained element
-     * @return an enum set containing the specified elements
+     *            another initially contained element.
+     * @return an enum set containing the specified elements.
      * @throws NullPointerException
-     *             if any of the specified elements is null
+     *             if any of the specified elements is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3, E e4) {
         EnumSet<E> set = of(e1, e2, e3);
@@ -217,22 +223,22 @@
     /**
      * Creates a new enum set, containing only the specified elements. There are
      * six overloadings of the method. They accept from one to five elements
-     * respectively. The sixth one receives arbitrary number of elements, and
-     * runs slower than those only receive fixed number of elements.
+     * respectively. The sixth one receives an arbitrary number of elements, and
+     * runs slower than those that only receive a fixed number of elements.
      * 
      * @param e1
-     *            the initially contained element
+     *            the initially contained element.
      * @param e2
-     *            another initially contained element
+     *            another initially contained element.
      * @param e3
-     *            another initially contained element
+     *            another initially contained element.
      * @param e4
-     *            another initially contained element
+     *            another initially contained element.
      * @param e5
-     *            another initially contained element
-     * @return an enum set containing the specified elements
+     *            another initially contained element.
+     * @return an enum set containing the specified elements.
      * @throws NullPointerException
-     *             if any of the specified elements is null
+     *             if any of the specified elements is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3, E e4, E e5) {
         EnumSet<E> set = of(e1, e2, e3, e4);
@@ -241,17 +247,17 @@
     }
 
     /**
-     * Creates a new enum set, containing only the specified elements. It
-     * receives arbitrary number of elements, and runs slower than those only
-     * receive fixed number of elements.
+     * Creates a new enum set, containing only the specified elements. It can
+     * receive an arbitrary number of elements, and runs slower than those only
+     * receiving a fixed number of elements.
      * 
      * @param start
-     *            the first initially contained element
+     *            the first initially contained element.
      * @param others
-     *            the other initially contained elements
-     * @return an enum set containing the specified elements
+     *            the other initially contained elements.
+     * @return an enum set containing the specified elements.
      * @throws NullPointerException
-     *             if any of the specified elements is null
+     *             if any of the specified elements is {@code null}.
      */
     public static <E extends Enum<E>> EnumSet<E> of(E start, E... others) {
         EnumSet<E> set = of(start);
@@ -263,17 +269,18 @@
 
     /**
      * Creates an enum set containing all the elements within the range defined
-     * by start and end (inclusive). All the elements must be in order.
+     * by {@code start} and {@code end} (inclusive). All the elements must be in
+     * order.
      * 
      * @param start
-     *            the element used to define the beginning of the range
+     *            the element used to define the beginning of the range.
      * @param end
-     *            the element used to define the end of the range
-     * @return an enum set with elements in the range from start to end
+     *            the element used to define the end of the range.
+     * @return an enum set with elements in the range from start to end.
      * @throws NullPointerException
-     *             if any one of start or end is null
+     *             if any one of {@code start} or {@code end} is {@code null}.
      * @throws IllegalArgumentException
-     *             if start is behind end
+     *             if {@code start} is behind {@code end}.
      */
     public static <E extends Enum<E>> EnumSet<E> range(E start, E end) {
         if (start.compareTo(end) > 0) {
@@ -291,7 +298,7 @@
      * enum set.
      * 
      * @return a new enum set with the same elements as those contained in this
-     *         enum set
+     *         enum set.
      */
     @SuppressWarnings("unchecked")
     @Override

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Enumeration.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Enumeration.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Enumeration.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Enumeration.java Thu May  7 21:43:41 2009
@@ -19,30 +19,31 @@
 
 /**
  * An Enumeration is used to sequence over a collection of objects.
- * 
+ * <p>
+ * Preferably an {@link Iterator} should be used. {@code Iterator} replaces the
+ * enumeration interface and adds a way to remove elements from a collection.
+ *
  * @see Hashtable
  * @see Properties
  * @see Vector
  * @version 1.0
  */
 public interface Enumeration<E> {
+
     /**
-     * Answers if this Enumeration has more elements.
-     * 
-     * @return true if there are more elements, false otherwise
+     * Returns whether this {@code Enumeration} has more elements.
      * 
+     * @return {@code true} if there are more elements, {@code false} otherwise.
      * @see #nextElement
      */
     public boolean hasMoreElements();
 
     /**
-     * Answers the next element in this Enumeration.
-     * 
-     * @return the next element in this Enumeration
-     * 
-     * @exception NoSuchElementException
-     *                when there are no more elements
+     * Returns the next element in this {@code Enumeration}.
      * 
+     * @return the next element..
+     * @throws NoSuchElementException
+     *             if there are no more elements.
      * @see #hasMoreElements
      */
     public E nextElement();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventListenerProxy.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventListenerProxy.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventListenerProxy.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventListenerProxy.java Thu May  7 21:43:41 2009
@@ -17,22 +17,30 @@
 
 package java.util;
 
+
 /**
- * This abstract class provides a simple wrapper to types of EventListener.
- * 
+ * This abstract class provides a simple wrapper for objects of type {@code EventListener}.
  */
 public abstract class EventListenerProxy implements EventListener {
 
     private final EventListener listener;
 
     /**
+     * Creates a new {@code EventListener} proxy instance.
+     * 
      * @param listener
+     *            the listener wrapped by this proxy.
      */
     public EventListenerProxy(EventListener listener) {
         super();
         this.listener = listener;
     }
 
+    /**
+     * Returns the wrapped {@code EventListener}.
+     * 
+     * @return the wrapped {@code EventListener}.
+     */
     public EventListener getListener() {
         return listener;
     }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventObject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventObject.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventObject.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/EventObject.java Thu May  7 21:43:41 2009
@@ -17,16 +17,17 @@
 
 package java.util;
 
+
 import java.io.Serializable;
 
 /**
- * EventObjects represent events. Typically applications subclass this class to
+ * {@code EventObject}s represent events. Typically applications subclass this class to
  * add event specific information.
  * 
  * @see EventListener
  */
 public class EventObject implements Serializable {
-
+    
     private static final long serialVersionUID = 5516075349620653480L;
 
     /**
@@ -38,7 +39,7 @@
      * Constructs a new instance of this class.
      * 
      * @param source
-     *            the object which fired the event
+     *            the object which fired the event.
      */
     public EventObject(Object source) {
         if (source != null) {
@@ -49,18 +50,18 @@
     }
 
     /**
-     * Answers the event source.
+     * Returns the event source.
      * 
-     * @return the object which fired the event
+     * @return the object which fired the event.
      */
     public Object getSource() {
         return source;
     }
 
     /**
-     * Answers the string representation of this EventObject.
+     * Returns the string representation of this {@code EventObject}.
      * 
-     * @return the string representation of this EventObject
+     * @return the string representation of this {@code EventObject}.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatFlagsConversionMismatchException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatFlagsConversionMismatchException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatFlagsConversionMismatchException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatFlagsConversionMismatchException.java Thu May  7 21:43:41 2009
@@ -19,8 +19,10 @@
 import java.io.Serializable;
 
 /**
- * The unchecked exception will be thrown out if a conversion and flags are
- * incompatible.
+ * A {@code FormatFlagsConversionMismatchException} will be thrown if a
+ * conversion and the flags are incompatible.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class FormatFlagsConversionMismatchException extends
         IllegalFormatException implements Serializable {
@@ -32,13 +34,13 @@
     private char c;
 
     /**
-     * Construct a FormatFlagsConversionMismatchException with the flags and
-     * conversion specified.
+     * Constructs a new {@code FormatFlagsConversionMismatchException} with the
+     * flags and conversion specified.
      * 
      * @param f
-     *            The flags
+     *           the flags.
      * @param c
-     *            The conversion
+     *           the conversion.
      */
     public FormatFlagsConversionMismatchException(String f, char c) {
         if (null == f) {
@@ -51,25 +53,25 @@
     /**
      * Returns the incompatible format flag.
      * 
-     * @return The incompatible format flag.
+     * @return the incompatible format flag.
      */
     public String getFlags() {
         return f;
     }
 
     /**
-     * Returns the incompatible Conversion.
+     * Returns the incompatible conversion.
      * 
-     * @return The incompatible Conversion.
+     * @return the incompatible conversion.
      */
     public char getConversion() {
         return c;
     }
 
     /**
-     * Returns the message string of the FormatFlagsConversionMismatchException.
+     * Returns the message string of the {@code FormatFlagsConversionMismatchException}.
      * 
-     * @return The message string of the FormatFlagsConversionMismatchException.
+     * @return the message string of the {@code FormatFlagsConversionMismatchException}.
      */
     @Override
     public String getMessage() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formattable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formattable.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formattable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formattable.java Thu May  7 21:43:41 2009
@@ -17,40 +17,42 @@
 package java.util;
 
 /**
- * Any class that need to perform customer formatting by transferring converter
- * specifier 's' to Formatter should implement the Formattable interface. Basic
- * format is allowed by the interface to format arbitrary objects.
+ * Classes that handle custom formatting for the 's' specifier of {@code Formatter}
+ * should implement the {@code Formattable} interface. It gives basic control over
+ * formatting objects.
+ *  
+ * @see Formatter
  */
 
 public interface Formattable {
 
     /**
-     * Formats the object using the specified formatter.
+     * Formats the object using the specified {@code Formatter}.
      * 
      * @param formatter
-     *            The formatter to use in the formatTo.
+     *            the {@code Formatter} to use.
      * @param flags
-     *            The flags applied to the output format, which is a bitmask
-     *            that is any combination of FormattableFlags.LEFT_JUSTIFY,
-     *            FormattableFlags.UPPERCASE, and FormattableFlags.ALTERNATE. If
+     *            the flags applied to the output format, which is a bitmask
+     *            that is any combination of {@code FormattableFlags.LEFT_JUSTIFY},
+     *            {@code FormattableFlags.UPPERCASE}, and {@code FormattableFlags.ALTERNATE}. If
      *            no such flag is set, the output is formatted by the default
-     *            formatting of the implementation of the interface.
+     *            formatting of the implementation.
      * @param width
-     *            The minimum number of characters that should be written to the
-     *            output. Additional space ' ' is added to the output if the
-     *            length of the converted value is less than the width until the
-     *            length equals the width. These spaces are added at the
+     *            the minimum number of characters that should be written to the
+     *            output. If the length of the converted value is less than {@code width}
+     *            Additional space characters (' ') are added to the output if the
+     *            as needed to make up the difference. These spaces are added at the
      *            beginning by default unless the flag
      *            FormattableFlags.LEFT_JUSTIFY is set, which denotes that
-     *            padding should be added at the end. If width is -1, then no
-     *            minimum requirement.
+     *            padding should be added at the end. If width is -1, then
+     *            minimum length is not enforced.
      * @param precision
-     *            The maximum number of characters that can be written to the
-     *            output. The procedure to trunk the output according to the
-     *            precision is invoked before that of padding to width. If the
-     *            precision is -1, then no maximum requirement.
+     *            the maximum number of characters that can be written to the
+     *            output. The length of the output is trimmed down to this size
+     *            before the width padding is applied. If the precision
+     *            is -1, then maximum length is not enforced.
      * @throws IllegalFormatException
-     *             If any of the parameters is not supported.
+     *             if any of the parameters is not supported.
      */
     void formatTo(Formatter formatter, int flags, int width, int precision)
             throws IllegalFormatException;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormattableFlags.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormattableFlags.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormattableFlags.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormattableFlags.java Thu May  7 21:43:41 2009
@@ -16,11 +16,13 @@
 package java.util;
 
 /**
- * FormattableFlags are used as a parameter to method Formattable.formatTo() and
- * instruct the output format in Formattables. The validation and interpretation
- * are fulfilled by the implementation of Formattable.
+ * FormattableFlags are used as a parameter to
+ * {@link Formattable#formatTo(Formatter, int, int, int)} and change the output
+ * format in {@code Formattable}s. The validation and interpretation of the
+ * flags must be done by the implementations.
+ *  
+ * @see Formattable
  */
-
 public class FormattableFlags {
     
     private FormattableFlags(){
@@ -28,29 +30,29 @@
     }
     
     /**
-     * Denotes the output to be left-justified. In order to fill the minimum
-     * width requirement, spaces('&#92;u0020') will be appended at the end of the
+     * Denotes the output is to be left-justified. In order to fill the minimum
+     * width requirement, spaces('\u0020') will be appended at the end of the
      * specified output element. If no such flag is set, the output is
      * right-justified.
      * 
-     * The flag corresponds to '-' ('&#92;u002d') in the format specifier.
+     * The flag corresponds to '-' ('\u002d') in the format specifier.
      */
     public static final int LEFT_JUSTIFY = 1;
 
     /**
-     * Denotes the output to be converted to upper case in the way the locale
+     * Denotes the output is to be converted to upper case in the way the locale
      * parameter of Formatter.formatTo() requires. The output has the same
-     * effect as String.toUpperCase(java.util.Locale).
+     * effect as {@code String.toUpperCase(java.util.Locale)}.
      * 
-     * This flag corresponds to '^' ('&#92;u005e') in the format specifier.
+     * This flag corresponds to {@code '^' ('\u005e')} in the format specifier.
      */
     public static final int UPPERCASE = 2;
 
     /**
-     * Denotes the output to be formatted in an alternate form. The definition
-     * of the alternate form is given out by Formattable.
+     * Denotes the output is to be formatted in an alternate form. The definition
+     * of the alternate form is determined by the {@code Formattable}.
      * 
-     * This flag corresponds to '#' ('&#92;u0023') in the format specifier.
+     * This flag corresponds to {@code '#' ('\u0023')} in the format specifier.
      */
     public static final int ALTERNATE = 4;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formatter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formatter.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formatter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Formatter.java Thu May  7 21:43:41 2009
@@ -39,22 +39,360 @@
 import java.text.NumberFormat;
 
 /**
- * Formatter provides the method to give out formatted string just like the
- * printf-style. Layout,alignment and other format flags are provided to format
- * numeric,string and date/time as well as locale-specified formats applied.
- * Besides primitive types, formatter also support some java object types such
- * as BigInteger,BigDecimal and Calendar. Customized formatting is provided
- * through the Formattable interface.
- * 
- * The class is not multi-threaded safe. The responsibility to maintain thread
- * safety is the user's job.
- * 
+ * <p>The {@code Formatter} class is a String-formatting utility that is designed
+ * to work like the {@code printf} function of the C programming language.
+ * Its key methods are the {@code format} methods which create a formatted
+ * {@code String} by replacing a set of placeholders (format tokens) with formatted
+ * values. The style used to format each value is determined by the format
+ * token used.  For example, the call<br/>
+ * {@code format("My decimal value is %d and my String is %s.", 3, "Hello");}<br/>
+ * returns the {@code String}<br/>
+ * {@code My decimal value is 3 and my String is Hello.}
+ *
+ * <p>The format token consists of a percent sign, optionally followed
+ * by flags and precision arguments, and then a single character that
+ * indicates the type of value
+ * being formatted.  If the type is a time/date, then the type character
+ * {@code t} is followed by an additional character that indicates how the
+ * date is to be formatted. The two characters {@code <$} immediately
+ * following the % sign indicate that the previous value should be used again
+ * instead of moving on to the next value argument. A number {@code n}
+ * and a dollar sign immediately following the % sign make n the next argument
+ * to be used.
+ *
+ * <p>The available choices are the following:
+ *
+ * <table BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Text value types</B></TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code s}</td>
+ * <td width="10%">String</td>
+ * <td width="30%">{@code format("%s, %s", "hello", "Hello");}</td>
+ * <td width="30%">{@code hello, Hello}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code S}, {@code s}</td>
+ * <td width="10%">String to capitals</td>
+ * <td width="30%">{@code format("%S, %S", "hello", "Hello");}</td>
+ * <td width="30%">{@code HELLO, HELLO}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code c}</td>
+ * <td width="10%">Character</td>
+ * <td width="30%">{@code format("%c, %c", 'd', 0x65);}</td>
+ * <td width="30%">{@code d, e}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code C}</td>
+ * <td width="10%">Character to capitals</td>
+ * <td width="30%">{@code format("%C, %C", 'd', 0x65);}</td>
+ * <td width="30%">{@code D, E}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Text option flags</B><br/>The value between the
+ * option and the type character indicates the minimum width in
+ * characters of the formatted value  </TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code -}</td>
+ * <td width="10%">Left justify (width value is required)</td>
+ * <td width="30%">{@code format("%-3C, %3C", 'd', 0x65);}</td>
+ * <td width="30%">{@code D  ,   E}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Integer types</B></TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code d}</td>
+ * <td width="10%">int, formatted as decimal</td>
+ * <td width="30%">{@code format("%d, %d"1$, 35, 0x10);}</td>
+ * <td width="30%">{@code 35, 16}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code o}</td>
+ * <td width="10%">int, formatted as octal</td>
+ * <td width="30%">{@code format("%o, %o", 8, 010);}</td>
+ * <td width="30%">{@code 10, 10}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code X}, {@code x}</td>
+ * <td width="10%">int, formatted as hexidecimal</td>
+ * <td width="30%">{@code format("%x, %X", 10, 10);}</td>
+ * <td width="30%">{@code a, A}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Integer option flags</B><br/>The value between the
+ * option and the type character indicates the minimum width in
+ * characters of the formatted value  </TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code +}</td>
+ * <td width="10%">lead with the number's sign</td>
+ * <td width="30%">{@code format("%+d, %+4d", 5, 5);}</td>
+ * <td width="30%">{@code +5,   +5}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code -}</td>
+ * <td width="10%">Left justify (width value is required)</td>
+ * <td width="30%">{@code format("%-6dx", 5);}</td>
+ * <td width="30%">{@code 5      x}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code #}</td>
+ * <td width="10%">Print the leading characters that indicate
+ * hexidecimal or octal (for use only with hex and octal types) </td>
+ * <td width="30%">{@code format("%#o", 010);}</td>
+ * <td width="30%">{@code 010}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code  }</td>
+ * <td width="10%">A space indicates that non-negative numbers
+ * should have a leading space. </td>
+ * <td width="30%">{@code format("x% d% 5d", 4, 4);}</td>
+ * <td width="30%">{@code x 4    4}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code 0}</td>
+ * <td width="10%">Pad the number with leading zeros (width value is required)</td>
+ * <td width="30%">{@code format("%07d, %03d", 4, 5555);}</td>
+ * <td width="30%">{@code 0000004, 5555}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code (}</td>
+ * <td width="10%">Put parentheses around negative numbers (decimal only)</td>
+ * <td width="30%">{@code format("%(d, %(d, %(6d", 12, -12, -12);}</td>
+ * <td width="30%">{@code 12, (12),   (12)}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Float types</B><br/>A value immediately following the % symbol
+ * gives the minimum width in characters of the formatted value; if it
+ * is followed by a period and another integer, then the second value
+ * gives the precision (6 by default).</TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code f}</td>
+ * <td width="10%">float (or double) formatted as a decimal, where
+ * the precision indicates the number of digits after the decimal.</td>
+ * <td width="30%">{@code format("%f %<.1f %<1.5f %<10f %<6.0f", 123.456f);}</td>
+ * <td width="30%">{@code 123.456001 123.5 123.45600 123.456001    123}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code E}, {@code e}</td>
+ * <td width="10%">float (or double) formatted in decimal exponential
+ * notation, where the precision indicates the number of significant digits.</td>
+ * <td width="30%">{@code format("%E %<.1e %<1.5E %<10E %<6.0E", 123.456f);}</td>
+ * <td width="30%">{@code 1.234560E+02 1.2e+02 1.23456E+02 1.234560E+02  1E+02}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code G}, {@code g}</td>
+ * <td width="10%">float (or double) formatted in decimal exponential
+ * notation , where the precision indicates the maximum number of significant digits.</td>
+ * <td width="30%">{@code format("%G %<.1g %<1.5G %<10G %<6.0G", 123.456f);}</td>
+ * <td width="30%">{@code 123.456 1e+02 123.46    123.456  1E+02}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code A}, {@code a}</td>
+ * <td width="10%">float (or double) formatted as a hexidecimal in exponential
+ * notation, where the precision indicates the number of significant digits.</td>
+ * <td width="30%">{@code format("%A %<.1a %<1.5A %<10A %<6.0A", 123.456f);}</td>
+ * <td width="30%">{@code 0X1.EDD2F2P6 0x1.fp6 0X1.EDD2FP6 0X1.EDD2F2P6 0X1.FP6}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Float-type option flags</B><br/>See the Integer-type options.
+ * The options for float-types are the
+ * same as for integer types with one addition: </TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code ,}</td>
+ * <td width="10%">Use a comma in place of a decimal if the locale
+ * requires it. </td>
+ * <td width="30%">{@code format(new Locale("fr"), "%,7.2f", 6.03f);}</td>
+ * <td width="30%">{@code    6,03}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Date types</B></TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code t}, {@code T}</td>
+ * <td width="10%">Date</td>
+ * <td width="30%">{@code format(new Locale("fr"), "%tB %TB", Calendar.getInstance(), Calendar.getInstance());}</td>
+ * <td width="30%">{@code avril AVRIL}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Date format precisions</B><br/>The format precision character
+ * follows the {@code t}. </TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code A}, {@code a}</td>
+ * <td width="10%">The day of the week</td>
+ * <td width="30%">{@code format("%ta %tA", cal, cal);}</td>
+ * <td width="30%">{@code Tue Tuesday}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code b}, {@code B}, {@code h}</td>
+ * <td width="10%">The name of the month</td>
+ * <td width="30%">{@code format("%tb %<tB %<th", cal, cal, cal);}</td>
+ * <td width="30%">{@code Apr April Apr}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code C}</td>
+ * <td width="10%">The century</td>
+ * <td width="30%">{@code format("%tC\n", cal);}</td>
+ * <td width="30%">{@code 20}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code d}, {@code e}</td>
+ * <td width="10%">The day of the month (with or without leading zeros)</td>
+ * <td width="30%">{@code format("%td %te", cal, cal);}</td>
+ * <td width="30%">{@code 01 1}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code F}</td>
+ * <td width="10%">The complete date formatted as YYYY-MM-DD</td>
+ * <td width="30%">{@code format("%tF", cal);}</td>
+ * <td width="30%">{@code 2008-04-01}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code D}</td>
+ * <td width="10%">The complete date formatted as MM/DD/YY
+ * (not corrected for locale) </td>
+ * <td width="30%">{@code format(new Locale("en_US"), "%tD", cal);<br/>format(new Locale("en_UK"), " %tD", cal);}</td>
+ * <td width="30%">{@code 04/01/08 04/01/08}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code j}</td>
+ * <td width="10%">The number of the day (from the beginning of the year).</td>
+ * <td width="30%">{@code format("%tj\n", cal);}</td>
+ * <td width="30%">{@code 092}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code m}</td>
+ * <td width="10%">The number of the month</td>
+ * <td width="30%">{@code format("%tm\n", cal);}</td>
+ * <td width="30%">{@code 04}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code y}, {@code Y}</td>
+ * <td width="10%">The year</td>
+ * <td width="30%">{@code format("%ty %tY", cal, cal);}</td>
+ * <td width="30%">{@code 08 2008}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code H}, {@code I}, {@code k}, {@code l}</td>
+ * <td width="10%">The hour of the day, in 12 or 24 hour format, with or
+ * without a leading zero</td>
+ * <td width="30%">{@code format("%tH %tI %tk %tl", cal, cal, cal, cal);}</td>
+ * <td width="30%">{@code 16 04 16 4}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code p}</td>
+ * <td width="10%">a.m. or p.m.</td>
+ * <td width="30%">{@code format("%tp %Tp", cal, cal);}</td>
+ * <td width="30%">{@code pm PM}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code M}, {@code S}, {@code L}, {@code N}</td>
+ * <td width="10%">The minutes, seconds, milliseconds, and nanoseconds</td>
+ * <td width="30%">{@code format("%tM %tS %tL %tN", cal, cal, cal, cal);}</td>
+ * <td width="30%">{@code 08 17 359 359000000}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code Z}, {@code z}</td>
+ * <td width="10%">The time zone: its abbreviation or offset from GMT</td>
+ * <td width="30%">{@code format("%tZ %tz", cal, cal);}</td>
+ * <td width="30%">{@code CEST +0100}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code R}, {@code r}, {@code T}</td>
+ * <td width="10%">The complete time</td>
+ * <td width="30%">{@code format("%tR %tr %tT", cal, cal, cal);}</td>
+ * <td width="30%">{@code 16:15 04:15:32 PM 16:15:32}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code s}, {@code Q}</td>
+ * <td width="10%">The number of seconds or milliseconds from "the epoch"
+ * (1 January 1970 00:00:00 UTC) </td>
+ * <td width="30%">{@code format("%ts %tQ", cal, cal);}</td>
+ * <td width="30%">{@code 1207059412 1207059412656}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code c}</td>
+ * <td width="10%">The complete time and date</td>
+ * <td width="30%">{@code format("%tc", cal);}</td>
+ * <td width="30%">{@code Tue Apr 01 16:19:17 CEST 2008}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Other data types</B></TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code B}, {@code b}</td>
+ * <td width="10%">Boolean</td>
+ * <td width="30%">{@code format("%b, %B", true, false);}</td>
+ * <td width="30%">{@code true, FALSE}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code H}, {@code h}</td>
+ * <td width="10%">Hashcode</td>
+ * <td width="30%">{@code format("%h, %H", obj, obj);}</td>
+ * <td width="30%">{@code 190d11, 190D11}</td>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code n}</td>
+ * <td width="10%">line separator</td>
+ * <td width="30%">{@code format("first%nsecond", "???");}</td>
+ * <td width="30%">{@code first<br/>second}</td>
+ * </tr>
+ * <tr BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+ * <TD COLSPAN=4>
+ * <B>Escape sequences</B></TD>
+ * </tr>
+ * <tr>
+ * <td width="5%">{@code %}</td>
+ * <td width="10%">Escape the % character</td>
+ * <td width="30%">{@code format("%d%%, %d", 50, 60);}</td>
+ * <td width="30%">{@code 50%, 60}</td>
+ * </tr>
+ * </table>
+ *
+ * <p>An instance of Formatter can be created to write the formatted
+ * output to standard types of output streams.  Its functionality can
+ * also be accessed through the format methods of an output stream
+ * or of {@code String}:<br/>
+ * {@code System.out.println(String.format("%ty\n", cal));}<br/>
+ * {@code System.out.format("%ty\n", cal);}
+ *
+ * <p>The class is not multi-threaded safe. The user is responsible for
+ * maintaining a thread-safe design if a {@code Formatter} is
+ * accessed by multiple threads. 
+ *
  * @since 1.5
  */
 public final class Formatter implements Closeable, Flushable {
 
+    /**
+     * The enumeration giving the available styles for formatting very large
+     * decimal numbers.
+     */
     public enum BigDecimalLayoutForm {
-        SCIENTIFIC, DECIMAL_FLOAT
+        /**
+         * Use scientific style for BigDecimals.
+         */
+        SCIENTIFIC,
+        /**
+         * Use normal decimal/float style for BigDecimals.
+         */
+        DECIMAL_FLOAT
     }
 
     private Appendable out;
@@ -66,54 +404,58 @@
     private IOException lastIOException;
 
     /**
-     * Constructs a formatter.
+     * Constructs a {@code Formatter}.
      * 
-     * The output is a StringBuilder which can be achieved by invoking the out
-     * method and whose contents can be attained by calling the toString method.
+     * The output is written to a {@code StringBuilder} which can be acquired by invoking
+     * {@link #out()} and whose content can be obtained by calling
+     * {@code toString()}.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      */
     public Formatter() {
         this(new StringBuilder(), Locale.getDefault());
     }
 
     /**
-     * Constructs a formatter of which the output is denoted.
+     * Constructs a {@code Formatter} whose output will be written to the
+     * specified {@code Appendable}.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The locale for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param a
-     *            The output of the formatter. If a is null, then a
-     *            StringBuilder will be used.
+     *            the output destination of the {@code Formatter}. If {@code a} is {@code null},
+     *            then a {@code StringBuilder} will be used.
      */
     public Formatter(Appendable a) {
         this(a, Locale.getDefault());
     }
 
     /**
-     * Constructs a formatter of which the locale is denoted.
+     * Constructs a {@code Formatter} with the specified {@code Locale}.
      * 
-     * The output destination is a StringBuilder which can be achieved by
-     * invoking the out method and whose contents can be attained by calling the
-     * toString method.
+     * The output is written to a {@code StringBuilder} which can be acquired by invoking
+     * {@link #out()} and whose content can be obtained by calling
+     * {@code toString()}.
      * 
      * @param l
-     *            The locale of the formatter. If l is null, then no
-     *            localization will be used.
+     *            the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null},
+     *            then no localization will be used.
      */
     public Formatter(Locale l) {
         this(new StringBuilder(), l);
     }
 
     /**
-     * Constructs a formatter of which the output and locale is denoted.
+     * Constructs a {@code Formatter} with the specified {@code Locale}
+     * and whose output will be written to the
+     * specified {@code Appendable}.
      * 
      * @param a
-     *            The output of the formatter. If a is null, then a
-     *            StringBuilder will be used.
+     *            the output destination of the {@code Formatter}. If {@code a} is {@code null},
+     *            then a {@code StringBuilder} will be used.
      * @param l
-     *            The locale of the formatter. If l is null, then no
-     *            localization will be used.
+     *            the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null},
+     *            then no localization will be used.
      */
     public Formatter(Appendable a, Locale l) {
         if (null == a) {
@@ -125,25 +467,24 @@
     }
 
     /**
-     * Constructs a formatter of which the filename is denoted.
+     * Constructs a {@code Formatter} whose output is written to the specified file.
      * 
-     * The charset of the formatter is the default charset of JVM.
+     * The charset of the {@code Formatter} is the default charset.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param fileName
-     *            The filename of the file that is used as the output
-     *            destination for the formatter. The file will be truncated to
+     *            the filename of the file that is used as the output
+     *            destination for the {@code Formatter}. The file will be truncated to
      *            zero size if the file exists, or else a new file will be
-     *            created. The output of the formatter is buffered.
-     * 
+     *            created. The output of the {@code Formatter} is buffered.
      * @throws FileNotFoundException
-     *             If the filename does not denote a normal and writable file,
-     *             or a new file cannot be created or any error rises when
+     *             if the filename does not denote a normal and writable file,
+     *             or if a new file cannot be created, or if any error arises when
      *             opening or creating the file.
      * @throws SecurityException
-     *             If there is a security manager and it denies writing to the
-     *             file in checkWrite(file.getPath()).
+     *             if there is a {@code SecurityManager} in place which denies permission
+     *             to write to the file in {@code checkWrite(file.getPath())}.
      */
     public Formatter(String fileName) throws FileNotFoundException {
         this(new File(fileName));
@@ -151,27 +492,26 @@
     }
 
     /**
-     * Constructs a formatter of which the filename and charset is denoted.
+     * Constructs a {@code Formatter} whose output is written to the specified file.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param fileName
-     *            The filename of the file that is used as the output
-     *            destination for the formatter. The file will be truncated to
+     *            the filename of the file that is used as the output
+     *            destination for the {@code Formatter}. The file will be truncated to
      *            zero size if the file exists, or else a new file will be
-     *            created. The output of the formatter is buffered.
+     *            created. The output of the {@code Formatter} is buffered.
      * @param csn
-     *            The name of the charset for the formatter.
-     * 
+     *            the name of the charset for the {@code Formatter}.
      * @throws FileNotFoundException
-     *             If the filename does not denote a normal and writable file,
-     *             or a new file cannot be created or any error rises when
+     *             if the filename does not denote a normal and writable file,
+     *             or if a new file cannot be created, or if any error arises when
      *             opening or creating the file.
      * @throws SecurityException
-     *             If there is a security manager and it denies writing to the
-     *             file in checkWrite(file.getPath()).
+     *             if there is a {@code SecurityManager} in place which denies permission
+     *             to write to the file in {@code checkWrite(file.getPath())}.
      * @throws UnsupportedEncodingException
-     *             If the charset with the specified name is not supported.
+     *             if the charset with the specified name is not supported.
      */
     public Formatter(String fileName, String csn) throws FileNotFoundException,
             UnsupportedEncodingException {
@@ -179,30 +519,28 @@
     }
 
     /**
-     * Constructs a formatter of which the filename, charset and locale is
-     * denoted.
+     * Constructs a {@code Formatter} with the given {@code Locale} and charset,
+     * and whose output is written to the specified file.
      * 
      * @param fileName
-     *            The filename of the file that is used as the output
-     *            destination for the formatter. The file will be truncated to
+     *            the filename of the file that is used as the output
+     *            destination for the {@code Formatter}. The file will be truncated to
      *            zero size if the file exists, or else a new file will be
-     *            created. The output of the formatter is buffered.
+     *            created. The output of the {@code Formatter} is buffered.
      * @param csn
-     *            The name of the charset for the formatter.
+     *            the name of the charset for the {@code Formatter}.
      * @param l
-     *            The locale of the formatter. If l is null, then no
-     *            localization will be used.
-     * 
+     *            the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null},
+     *            then no localization will be used.
      * @throws FileNotFoundException
-     *             If the filename does not denote a normal and writable file,
-     *             or a new file cannot be created or any error rises when
+     *             if the filename does not denote a normal and writable file,
+     *             or if a new file cannot be created, or if any error arises when
      *             opening or creating the file.
      * @throws SecurityException
-     *             If there is a security manager and it denies writing to the
-     *             file in checkWrite(file.getPath()).
+     *             if there is a {@code SecurityManager} in place which denies permission
+     *             to write to the file in {@code checkWrite(file.getPath())}.
      * @throws UnsupportedEncodingException
-     *             If the charset with the specified name is not supported.
-     * 
+     *             if the charset with the specified name is not supported.
      */
     public Formatter(String fileName, String csn, Locale l)
             throws FileNotFoundException, UnsupportedEncodingException {
@@ -211,51 +549,51 @@
     }
 
     /**
-     * Constructs a formatter of which the file is denoted.
+     * Constructs a {@code Formatter} whose output is written to the specified {@code File}.
      * 
-     * The charset of the formatter is the default charset of JVM.
+     * The charset of the {@code Formatter} is the default charset.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param file
-     *            The file that is used as the output destination for the
-     *            formatter. The file will be truncated to zero size if the file
-     *            exists, or else a new file will be created. The output of the
-     *            formatter is buffered.
-     * 
+     *            the {@code File} that is used as the output destination for the
+     *            {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File}
+     *            exists, or else a new {@code File} will be created. The output of the
+     *            {@code Formatter} is buffered.
      * @throws FileNotFoundException
-     *             If the file does not denote a normal and writable file, or a
-     *             new file cannot be created or any error rises when opening or
-     *             creating the file.
+     *             if the {@code File} is not a normal and writable {@code File}, or if a
+     *             new {@code File} cannot be created, or if any error rises when opening or
+     *             creating the {@code File}.
      * @throws SecurityException
-     *             If there is a security manager and it denies writing to the
-     *             file in checkWrite(file.getPath()).
+     *             if there is a {@code SecurityManager} in place which denies permission
+     *             to write to the {@code File} in {@code checkWrite(file.getPath())}.
      */
     public Formatter(File file) throws FileNotFoundException {
         this(new FileOutputStream(file));
     }
 
     /**
-     * Constructs a formatter of which the file and charset is denoted.
+     * Constructs a {@code Formatter} with the given charset,
+     * and whose output is written to the specified {@code File}.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param file
-     *            The file of the file that is used as the output destination
-     *            for the formatter. The file will be truncated to zero size if
-     *            the file exists, or else a new file will be created. The
-     *            output of the formatter is buffered.
+     *            the {@code File} that is used as the output destination for the
+     *            {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File}
+     *            exists, or else a new {@code File} will be created. The output of the
+     *            {@code Formatter} is buffered.
      * @param csn
-     *            The name of the charset for the formatter.
+     *            the name of the charset for the {@code Formatter}.
      * @throws FileNotFoundException
-     *             If the file does not denote a normal and writable file, or a
-     *             new file cannot be created or any error rises when opening or
-     *             creating the file.
+     *             if the {@code File} is not a normal and writable {@code File}, or if a
+     *             new {@code File} cannot be created, or if any error rises when opening or
+     *             creating the {@code File}.
      * @throws SecurityException
-     *             If there is a security manager and it denies writing to the
-     *             file in checkWrite(file.getPath()).
+     *             if there is a {@code SecurityManager} in place which denies permission
+     *             to write to the {@code File} in {@code checkWrite(file.getPath())}.
      * @throws UnsupportedEncodingException
-     *             If the charset with the specified name is not supported.
+     *             if the charset with the specified name is not supported.
      */
     public Formatter(File file, String csn) throws FileNotFoundException,
             UnsupportedEncodingException {
@@ -263,27 +601,28 @@
     }
 
     /**
-     * Constructs a formatter of which the file, charset and locale is denoted.
+     * Constructs a {@code Formatter} with the given {@code Locale} and charset,
+     * and whose output is written to the specified {@code File}.
      * 
      * @param file
-     *            file that is used as the output destination for the formatter.
-     *            The file will be truncated to zero size if the file exists, or
-     *            else a new file will be created. The output of the formatter
-     *            is buffered.
+     *            the {@code File} that is used as the output destination for the
+     *            {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File}
+     *            exists, or else a new {@code File} will be created. The output of the
+     *            {@code Formatter} is buffered.
      * @param csn
-     *            The name of the charset for the formatter.
+     *            the name of the charset for the {@code Formatter}.
      * @param l
-     *            The locale of the formatter. If l is null, then no
-     *            localization will be used.
+     *            the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null},
+     *            then no localization will be used.
      * @throws FileNotFoundException
-     *             If the file does not denote a normal and writable file, or a
-     *             new file cannot be created or any error rises when opening or
-     *             creating the file.
+     *             if the {@code File} is not a normal and writable {@code File}, or if a
+     *             new {@code File} cannot be created, or if any error rises when opening or
+     *             creating the {@code File}.
      * @throws SecurityException
-     *             If there is a security manager and it denies writing to the
-     *             file in checkWrite(file.getPath()).
+     *             if there is a {@code SecurityManager} in place which denies permission
+     *             to write to the {@code File} in {@code checkWrite(file.getPath())}.
      * @throws UnsupportedEncodingException
-     *             If the charset with the specified name is not supported.
+     *             if the charset with the specified name is not supported.
      */
     public Formatter(File file, String csn, Locale l)
             throws FileNotFoundException, UnsupportedEncodingException {
@@ -304,14 +643,14 @@
     }
 
     /**
-     * Constructs a formatter of which the output destination is specified.
+     * Constructs a {@code Formatter} whose output is written to the specified {@code OutputStream}.
      * 
-     * The charset of the formatter is the default charset of JVM.
+     * The charset of the {@code Formatter} is the default charset.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param os
-     *            The stream used as the destination of the formatter.
+     *            the stream to be used as the destination of the {@code Formatter}.
      */
     public Formatter(OutputStream os) {
         OutputStreamWriter writer = new OutputStreamWriter(os, Charset
@@ -321,17 +660,17 @@
     }
 
     /**
-     * Constructs a formatter of which the output destination and the charset is
-     * specified.
+     * Constructs a {@code Formatter} with the given charset,
+     * and whose output is written to the specified {@code OutputStream}.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param os
-     *            The stream used as the destination of the formatter.
+     *            the stream to be used as the destination of the {@code Formatter}.
      * @param csn
-     *            The name of the charset for the formatter.
+     *            the name of the charset for the {@code Formatter}.
      * @throws UnsupportedEncodingException
-     *             If the charset with the specified name is not supported.
+     *             if the charset with the specified name is not supported.
      */
     public Formatter(OutputStream os, String csn)
             throws UnsupportedEncodingException {
@@ -340,18 +679,18 @@
     }
 
     /**
-     * Constructs a formatter of which the output destination, the charset and
-     * the locale is specified.
+     * Constructs a {@code Formatter} with the given {@code Locale} and charset,
+     * and whose output is written to the specified {@code OutputStream}.
      * 
      * @param os
-     *            The stream used as the destination of the formatter.
+     *            the stream to be used as the destination of the {@code Formatter}.
      * @param csn
-     *            The name of the charset for the formatter.
+     *            the name of the charset for the {@code Formatter}.
      * @param l
-     *            The locale of the formatter. If l is null, then no
-     *            localization will be used.
+     *            the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null},
+     *            then no localization will be used.
      * @throws UnsupportedEncodingException
-     *             If the charset with the specified name is not supported.
+     *             if the charset with the specified name is not supported.
      */
     public Formatter(OutputStream os, String csn, Locale l)
             throws UnsupportedEncodingException {
@@ -363,15 +702,16 @@
     }
 
     /**
-     * Constructs a formatter of which the output destination is specified.
+     * Constructs a {@code Formatter} whose output is written to the specified {@code PrintStream}.
      * 
-     * The charset of the formatter is the default charset of JVM.
+     * The charset of the {@code Formatter} is the default charset.
      * 
-     * The locale for the formatter is the default locale of the JVM.
+     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
      * 
      * @param ps
-     *            The print stream used as destination of the formatter. If ps
-     *            is null, then NullPointerExcepiton will be thrown out.
+     *            the {@code PrintStream} used as destination of the {@code Formatter}. If
+     *            {@code ps} is {@code null}, then a {@code NullPointerException} will
+     *            be raised.
      */
     public Formatter(PrintStream ps) {
         if (null == ps) {
@@ -388,11 +728,11 @@
     }
 
     /**
-     * Returns the locale of the formatter.
+     * Returns the {@code Locale} of the {@code Formatter}.
      * 
-     * @return The locale for the formatter and null for no locale.
+     * @return the {@code Locale} for the {@code Formatter} or {@code null} for no {@code Locale}.
      * @throws FormatterClosedException
-     *             If the formatter has been closed.
+     *             if the {@code Formatter} has been closed.
      */
     public Locale locale() {
         checkClosed();
@@ -400,11 +740,11 @@
     }
 
     /**
-     * Returns the output destination of the formatter.
+     * Returns the output destination of the {@code Formatter}.
      * 
-     * @return The output destination of the formatter.
+     * @return the output destination of the {@code Formatter}.
      * @throws FormatterClosedException
-     *             If the formatter has been closed.
+     *             if the {@code Formatter} has been closed.
      */
     public Appendable out() {
         checkClosed();
@@ -412,13 +752,13 @@
     }
 
     /**
-     * Returns the content by calling the toString() method of the output
+     * Returns the content by calling the {@code toString()} method of the output
      * destination.
      * 
-     * @return The content by calling the toString() method of the output
+     * @return the content by calling the {@code toString()} method of the output
      *         destination.
      * @throws FormatterClosedException
-     *             If the formatter has been closed.
+     *             if the {@code Formatter} has been closed.
      */
     @Override
     public String toString() {
@@ -427,11 +767,11 @@
     }
 
     /**
-     * Flushes the formatter. If the output destination is {@link Flushable},
-     * then the method flush() will be called on that destination.
+     * Flushes the {@code Formatter}. If the output destination is {@link Flushable},
+     * then the method {@code flush()} will be called on that destination.
      * 
      * @throws FormatterClosedException
-     *             If the formatter has been closed.
+     *             if the {@code Formatter} has been closed.
      */
     public void flush() {
         checkClosed();
@@ -445,14 +785,14 @@
     }
 
     /**
-     * Closes the formatter. If the output destination is {@link Closeable},
-     * then the method close() will be called on that destination.
+     * Closes the {@code Formatter}. If the output destination is {@link Closeable},
+     * then the method {@code close()} will be called on that destination.
      * 
-     * If the formatter has been closed, then calling the close will have no
+     * If the {@code Formatter} has been closed, then calling the this method will have no
      * effect.
      * 
-     * Any method but the ioException() that is called after the formatter has
-     * been closed will raise a FormatterClosedException.
+     * Any method but the {@link #ioException()} that is called after the
+     * {@code Formatter} has been closed will raise a {@code FormatterClosedException}.
      */
     public void close() {
         closed = true;
@@ -467,11 +807,11 @@
     }
 
     /**
-     * Returns the last IOException thrown out by the formatter's output
-     * destination. If the append() method of the destination will not throw
-     * IOException, the ioException() method will always return null.
+     * Returns the last {@code IOException} thrown by the {@code Formatter}'s output
+     * destination. If the {@code append()} method of the destination does not throw
+     * {@code IOException}s, the {@code ioException()} method will always return {@code null}.
      * 
-     * @return The last IOException thrown out by the formatter's output
+     * @return the last {@code IOException} thrown by the {@code Formatter}'s output
      *         destination.
      */
     public IOException ioException() {
@@ -479,46 +819,47 @@
     }
 
     /**
-     * Writes a formatted string to the output destination of the formatter.
+     * Writes a formatted string to the output destination of the {@code Formatter}.
      * 
      * @param format
-     *            A format string.
+     *            a format string.
      * @param args
-     *            The arguments list used in the format() method. If there are
+     *            the arguments list used in the {@code format()} method. If there are
      *            more arguments than those specified by the format string, then
      *            the additional arguments are ignored.
-     * @return This formatter.
+     * @return this {@code Formatter}.
      * @throws IllegalFormatException
-     *             If the format string is illegal or incompatible with the
-     *             arguments or the arguments are less than those required by
-     *             the format string or any other illegal situation.
+     *             if the format string is illegal or incompatible with the
+     *             arguments, or if fewer arguments are sent than those required by
+     *             the format string, or any other illegal situation.
      * @throws FormatterClosedException
-     *             If the formatter has been closed.
+     *             if the {@code Formatter} has been closed.
      */
     public Formatter format(String format, Object... args) {
         return format(locale, format, args);
     }
 
     /**
-     * Writes a formatted string to the output destination of the formatter.
+     * Writes a formatted string to the output destination of the {@code Formatter}.
      * 
      * @param l
-     *            The locale used in the method. If locale is null, then no
-     *            localization will be applied. This parameter does not
-     *            influence the locale specified during construction.
+     *            the {@code Locale} used in the method. If {@code locale} is
+     *            {@code null}, then no localization will be applied. This
+     *            parameter does not influence the {@code Locale} specified during
+     *            construction.
      * @param format
-     *            A format string.
+     *            a format string.
      * @param args
-     *            The arguments list used in the format() method. If there are
+     *            the arguments list used in the {@code format()} method. If there are
      *            more arguments than those specified by the format string, then
      *            the additional arguments are ignored.
-     * @return This formatter.
+     * @return this {@code Formatter}.
      * @throws IllegalFormatException
-     *             If the format string is illegal or incompatible with the
-     *             arguments or the arguments are less than those required by
-     *             the format string or any other illegal situation.
+     *             if the format string is illegal or incompatible with the
+     *             arguments, or if fewer arguments are sent than those required by
+     *             the format string, or any other illegal situation.
      * @throws FormatterClosedException
-     *             If the formatter has been closed.
+     *             if the {@code Formatter} has been closed.
      */
     public Formatter format(Locale l, String format, Object... args) {
         checkClosed();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatterClosedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatterClosedException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatterClosedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/FormatterClosedException.java Thu May  7 21:43:41 2009
@@ -19,15 +19,18 @@
 import java.io.Serializable;
 
 /**
- * The unchecked exception will be thrown out if the formatter has been closed.
+ * A {@code FormatterClosedException} will be thrown if the formatter has been
+ * closed.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class FormatterClosedException extends IllegalStateException implements
         Serializable {
-
     private static final long serialVersionUID = 18111216L;
 
     /**
-     * Constructs an instance of FormatterClosedException.
+     * Constructs a new {@code FormatterClosedException} with the stack trace
+     * filled in.
      */
     public FormatterClosedException() {
     }



Mime
View raw message