harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [8/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/Map.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Map.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Map.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Map.java Thu May  7 21:43:41 2009
@@ -17,151 +17,156 @@
 
 package java.util;
 
+
 /**
- * Map has a set of keys, each key is mapped to a single value.
+ * A {@code Map} is a data structure consisting of a set of keys and values
+ * in which each key is mapped to a single value.  The class of the objects
+ * used as keys is declared when the {@code Map} is declared, as is the 
+ * class of the corresponding values.
+ * <p>
+ * A {@code Map} provides helper methods to iterate through all of the
+ * keys contained in it, as well as various methods to access and update 
+ * the key/value pairs.  
  */
-public interface Map<K, V> {
+public interface Map<K,V> {
 
     /**
-     * Map.Entry is a key/value mapping which is contained in a Map.
+     * {@code Map.Entry} is a key/value mapping contained in a {@code Map}.
      */
-    public static interface Entry<K, V> {
+    public static interface Entry<K,V> {
         /**
-         * Compares the specified object to this Map.Entry and answer if they
-         * are equal. The object must be an instance of Map.Entry and have the
+         * Compares the specified object to this {@code Map.Entry} and returns if they
+         * are equal. To be equal, the object must be an instance of {@code Map.Entry} and have the
          * same key and value.
          * 
          * @param object
-         *            the object to compare with this object
-         * @return true if the specified object is equal to this Map.Entry,
-         *         false otherwise
-         * 
-         * @see #hashCode
+         *            the {@code Object} to compare with this {@code Object}.
+         * @return {@code true} if the specified {@code Object} is equal to this
+         *         {@code Map.Entry}, {@code false} otherwise.
+         * @see #hashCode()
          */
         public boolean equals(Object object);
 
         /**
-         * Gets the key.
+         * Returns the key.
          * 
          * @return the key
          */
         public K getKey();
 
         /**
-         * Gets the value.
+         * Returns the value.
          * 
          * @return the value
          */
         public V getValue();
 
         /**
-         * 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. {@code Object} which are
+         * equal return the same value for this method.
          * 
-         * @return the receiver's hash
-         * 
-         * @see #equals
+         * @return the receiver's hash code.
+         * @see #equals(Object)
          */
         public int hashCode();
 
         /**
-         * Sets the value.
+         * Sets the value of this entry to the specified value, replacing any
+         * existing value.
          * 
          * @param object
-         *            the new value
-         * @return object
+         *            the new value to set.
+         * @return object the replaced value of this entry.
          */
         public V setValue(V object);
-    }
+    };
 
     /**
-     * Removes all elements from this Map, leaving it empty.
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Map is not supported
+     * Removes all elements from this {@code Map}, leaving it empty.
      * 
-     * @see #isEmpty
-     * @see #size
+     * @throws UnsupportedOperationException
+     *                if removing elements from this {@code Map} is not supported.
+     * @see #isEmpty()
+     * @see #size()
      */
     public void clear();
 
     /**
-     * Searches this Map for the specified key.
+     * Returns whether this {@code 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.
      */
     public boolean containsKey(Object key);
 
     /**
-     * Searches this Map for the specified value.
+     * Returns whether this {@code 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.
      */
     public boolean containsValue(Object value);
 
     /**
-     * Returns a <code>Set</code> whose elements comprise all of the mappings
-     * that are to be found in this <code>Map</code>. Information on each of
-     * the mappings is encapsulated in a separate {@link Map.Entry} instance. As
-     * the <code>Set</code> is backed by this <code>Map</code>, users
-     * should be aware that changes in one will be immediately visible in the
-     * other.
+     * Returns a {@code Set} containing all of the mappings in this {@code Map}. Each mapping is
+     * an instance of {@link Map.Entry}. As the {@code Set} is backed by this {@code Map},
+     * changes in one will be reflected in the other.
      * 
-     * @return a <code>Set</code> of the mappings
+     * @return a set of the mappings
      */
-    public Set<Map.Entry<K, V>> entrySet();
+    public Set<Map.Entry<K,V>> entrySet();
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the <em>same</em> object using a class specific comparison.
+     * Compares the argument to the receiver, and returns {@code true} if the
+     * specified object is a {@code Map} and both {@code Map}s contain the same mappings.
      * 
      * @param object
-     *            Object the object to compare with this object.
-     * @return boolean <code>true</code> if the object is the same as this
-     *         object <code>false</code> if it is different from this object.
-     * @see #hashCode
+     *            the {@code Object} to compare with this {@code Object}.
+     * @return boolean {@code true} if the {@code Object} is the same as this {@code Object}
+     *         {@code false} if it is different from this {@code Object}.
+     * @see #hashCode()
+     * @see #entrySet()
      */
     public boolean equals(Object object);
 
     /**
-     * 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.
      */
     public V get(Object key);
 
     /**
-     * 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. {@code Object}s which are equal
+     * return the same value for this method.
      * 
-     * @return the receiver's hash
-     * 
-     * @see #equals
+     * @return the receiver's hash.
+     * @see #equals(Object)
      */
     public int hashCode();
 
     /**
-     * Answers if this Map has no elements, a size of zero.
-     * 
-     * @return true if this Map 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()
      */
     public boolean isEmpty();
 
     /**
-     * Answers 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
+     * Returns a set of the keys contained in this {@code Map}. The {@code Set} is backed by
+     * this {@code Map} so changes to one are reflected by the other. The {@code Set} does not
      * support adding.
      * 
-     * @return a Set of the keys
+     * @return a set of the keys.
      */
     public Set<K> keySet();
 
@@ -169,71 +174,80 @@
      * 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
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this Map is not supported
-     * @exception ClassCastException
-     *                when the class of the key or value is inappropriate for
-     *                this Map
-     * @exception IllegalArgumentException
-     *                when the key or value cannot be added to this Map
-     * @exception NullPointerException
-     *                when the key or value is null and this Map does not
-     *                support null keys or values
+     *            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 {@code Map} is not supported.
+     * @throws ClassCastException
+     *                if the class of the key or value is inappropriate for
+     *                this {@code Map}.
+     * @throws IllegalArgumentException
+     *                if the key or value cannot be added to this {@code Map}.
+     * @throws NullPointerException
+     *                if the key or value is {@code null} and this {@code Map} does
+     *                not support {@code null} keys or values.
      */
     public V put(K key, V value);
 
     /**
-     * Copies every mapping in the specified Map to this Map.
+     * Copies every mapping in the specified {@code Map} to this {@code Map}.
      * 
      * @param map
-     *            the Map to copy mappings from
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this Map is not supported
-     * @exception ClassCastException
-     *                when the class of a key or value is inappropriate for this
-     *                Map
-     * @exception IllegalArgumentException
-     *                when a key or value cannot be added to this Map
-     * @exception NullPointerException
-     *                when a key or value is null and this Map does not support
-     *                null keys or values
+     *            the {@code Map} to copy mappings from.
+     * @throws UnsupportedOperationException
+     *                if adding to this {@code Map} is not supported.
+     * @throws ClassCastException
+     *                if the class of a key or a value of the specified {@code Map} is
+     *                inappropriate for this {@code Map}.
+     * @throws IllegalArgumentException
+     *                if a key or value cannot be added to this {@code Map}.
+     * @throws NullPointerException
+     *                if a key or value is {@code null} and this {@code Map} does not
+     *                support {@code null} keys or values.
      */
-    public void putAll(Map<? extends K, ? extends V> map);
+    public void putAll(Map<? extends K,? extends V> map);
 
     /**
-     * Removes a mapping with the specified key from this Map.
+     * Removes a mapping with the specified key from this {@code 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
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Map is not supported
+     *            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 Map} is not supported.
      */
     public V remove(Object key);
 
     /**
-     * Answers the number of elements in this Map.
+     * Returns the number of mappings in this {@code Map}.
      * 
-     * @return the number of elements in this Map
+     * @return the number of mappings in this {@code Map}.
      */
     public int size();
 
     /**
-     * Returns all of the current <code>Map</code> values in a
-     * <code>Collection</code>. As the returned <code>Collection</code> is
-     * backed by this <code>Map</code>, users should be aware that changes in
-     * one will be immediately visible in the other.
+     * Returns a {@code Collection} of the values contained in this {@code Map}. The {@code Collection}
+     * is backed by this {@code Map} so changes to one are reflected by the other. The
+     * {@code Collection} supports {@link Collection#remove}, {@link Collection#removeAll}, 
+     * {@link Collection#retainAll}, and {@link Collection#clear} operations,
+     * and it does not support {@link Collection#add} or {@link Collection#addAll} operations.
+     * <p>
+     * This method returns a {@code Collection} which is the subclass of
+     * {@link AbstractCollection}. The {@link AbstractCollection#iterator} method of this subclass returns a
+     * "wrapper object" over the iterator of this {@code Map}'s {@link #entrySet()}. The {@link AbstractCollection#size} method
+     * wraps this {@code Map}'s {@link #size} method and the {@link AbstractCollection#contains} method wraps this {@code Map}'s
+     * {@link #containsValue} method.
+     * <p>
+     * The collection is created when this method is called at first time and
+     * returned in response to all subsequent calls. This method may return
+     * different Collection when multiple calls to this method, since it has no
+     * synchronization performed.
      * 
-     * @return a Collection of the values
+     * @return a collection of the values contained in this map.
      */
     public Collection<V> values();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatArgumentException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatArgumentException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatArgumentException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatArgumentException.java Thu May  7 21:43:41 2009
@@ -19,22 +19,23 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * The unchecked exception will be thrown out if there no corresponding argument
- * with the specified conversion or an argument index that refers to a missing
- * argument.
+ * A {@code MissingFormatArgumentException} will be thrown if there is no
+ * corresponding argument with the specified conversion or an argument index
+ * that refers to a missing argument.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class MissingFormatArgumentException extends IllegalFormatException {
-
     private static final long serialVersionUID = 19190115L;
 
     private String s;
 
     /**
-     * Constructs an MissingFormatArgumentException with the specified
-     * conversion that lacks the argument.
+     * Constructs a new {@code MissingFormatArgumentException} with the
+     * specified conversion that lacks the argument.
      * 
      * @param s
-     *            The specified conversion that lacks the argument.
+     *           the specified conversion that lacks the argument.
      */
     public MissingFormatArgumentException(String s) {
         if (null == s) {
@@ -46,7 +47,7 @@
     /**
      * Returns the conversion associated with the exception.
      * 
-     * @return The conversion associated with the exception.
+     * @return the conversion associated with the exception.
      */
     public String getFormatSpecifier() {
         return s;
@@ -55,7 +56,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/MissingFormatWidthException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatWidthException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatWidthException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingFormatWidthException.java Thu May  7 21:43:41 2009
@@ -17,21 +17,22 @@
 package java.util;
 
 /**
- * The unchecked exception will be thrown out if the format width is missing but
- * is required.
+ * A {@code MissingFormatWidthException} will be thrown if the format width is
+ * missing but is required.
+ * 
+ * @see java.lang.RuntimeException
  */
 public class MissingFormatWidthException extends IllegalFormatException {
-
     private static final long serialVersionUID = 15560123L;
 
     private String s;
 
     /**
-     * Constructs a MissingFormatWidthException with the specified format
-     * specifier.
+     * Constructs a new {@code MissingFormatWidthException} with the specified
+     * format specifier.
      * 
      * @param s
-     *            The specified format specifier.
+     *           the specified format specifier.
      */
     public MissingFormatWidthException(String s) {
         if (null == s) {
@@ -43,7 +44,7 @@
     /**
      * Returns the format specifier associated with the exception.
      * 
-     * @return The format specifier associated with the exception.
+     * @return the format specifier associated with the exception.
      */
     public String getFormatSpecifier() {
         return s;
@@ -52,7 +53,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/MissingResourceException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingResourceException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingResourceException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/MissingResourceException.java Thu May  7 21:43:41 2009
@@ -17,11 +17,14 @@
 
 package java.util;
 
+
 /**
- * This runtime exception is thrown by ResourceBundle when a resouce bundle
- * cannot be found or a resource is missing from a resource bundle.
+ * A {@code MissingResourceException} is thrown by ResourceBundle when a
+ * resource bundle cannot be found or a resource is missing from a resource
+ * bundle.
  * 
  * @see ResourceBundle
+ * @see java.lang.RuntimeException
  */
 public class MissingResourceException extends RuntimeException {
 
@@ -30,15 +33,16 @@
     String className, key;
 
     /**
-     * Constructs a new instance of this class with its walkback, message, the
-     * class name of the resource bundle and the name of the missing resource.
+     * Constructs a new {@code MissingResourceException} with the stack trace,
+     * message, the class name of the resource bundle and the name of the
+     * missing resource filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *           the detail message for the exception.
      * @param className
-     *            String The class name of the resource bundle.
+     *           the class name of the resource bundle.
      * @param resourceName
-     *            String The name of the missing resource.
+     *           the name of the missing resource.
      */
     public MissingResourceException(String detailMessage, String className,
             String resourceName) {
@@ -48,21 +52,21 @@
     }
 
     /**
-     * Answers the class name of the resource bundle from which a resource could
+     * Returns the class name of the resource bundle from which a resource could
      * not be found, or in the case of a missing resource, the name of the
      * missing resource bundle.
      * 
-     * @return String The class name of the resource bundle.
+     * @return the class name of the resource bundle.
      */
     public String getClassName() {
         return className;
     }
 
     /**
-     * Answers the name of the missing resource, or an empty string if the
+     * Returns the name of the missing resource, or an empty string if the
      * resource bundle is missing.
      * 
-     * @return String The name of the missing resource.
+     * @return the name of the missing resource.
      */
     public String getKey() {
         return key;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/NoSuchElementException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/NoSuchElementException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/NoSuchElementException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/NoSuchElementException.java Thu May  7 21:43:41 2009
@@ -17,9 +17,11 @@
 
 package java.util;
 
+
 /**
- * This runtime exception is thrown when trying to retrieve an element past the
- * end of an Enumeration, or the first or last element from an empty Vector.
+ * A {@code NoSuchElementException} is thrown when trying to retrieve an element
+ * past the end of an Enumeration, or the first or last element from an empty
+ * Vector.
  * 
  * @see Enumeration
  * @see java.lang.RuntimeException
@@ -29,18 +31,19 @@
     private static final long serialVersionUID = 6769829250639411880L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code NoSuchElementException} with the current stack
+     * trace filled in.
      */
     public NoSuchElementException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code NoSuchElementException} with the current stack
+     * trace and message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *           the detail message for the exception.
      */
     public NoSuchElementException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observable.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observable.java Thu May  7 21:43:41 2009
@@ -19,7 +19,14 @@
 
 /**
  * Observable is used to notify a group of Observer objects when a change
- * occurs.
+ * occurs. On creation, the set of observers is empty. After a change occurred,
+ * the application can call the {@link #notifyObservers()} method. This will
+ * cause the invocation of the {@code update()} method of all registered
+ * Observers. The order of invocation is not specified. This implementation will
+ * call the Observers in the order they registered. Subclasses are completely
+ * free in what order they call the update methods.
+ *
+ * @see Observer
  */
 public class Observable {
 
@@ -28,17 +35,18 @@
     boolean changed = false;
 
     /**
-     * Constructs a new Observable object.
+     * Constructs a new {@code Observable} object.
      */
     public Observable() {
         super();
     }
 
     /**
-     * Adds the specified Observer to the list of observers.
+     * Adds the specified observer to the list of observers. If it is already
+     * registered, it is not added a second time.
      * 
      * @param observer
-     *            the Observer to add
+     *            the Observer to add.
      */
     public void addObserver(Observer observer) {
         if (observer == null) {
@@ -51,70 +59,68 @@
     }
 
     /**
-     * Clears the changed flag for this Observable. After calling
-     * <code>clearChanged()</code>, <code>hasChanged()</code> will return
-     * false.
+     * Clears the changed flag for this {@code Observable}. After calling
+     * {@code clearChanged()}, {@code hasChanged()} will return {@code false}.
      */
     protected void clearChanged() {
         changed = false;
     }
 
     /**
-     * Answers the number of Observers in the list of observers.
+     * Returns the number of observers registered to this {@code Observable}.
      * 
-     * @return the number of observers
+     * @return the number of observers.
      */
     public int countObservers() {
         return observers.size();
     }
 
     /**
-     * Removes the specified Observer from the list of observers.
+     * Removes the specified observer from the list of observers. Passing null
+     * won't do anything.
      * 
      * @param observer
-     *            the Observer to remove
+     *            the observer to remove.
      */
     public synchronized void deleteObserver(Observer observer) {
         observers.remove(observer);
     }
 
     /**
-     * Removes all Observers from the list of observers.
+     * Removes all observers from the list of observers.
      */
     public synchronized void deleteObservers() {
         observers.clear();
     }
 
     /**
-     * Answers the changed flag for this Observable.
+     * Returns the changed flag for this {@code Observable}.
      * 
-     * @return true when the changed flag for this Observable is set, false
-     *         otherwise
+     * @return {@code true} when the changed flag for this {@code Observable} is
+     *         set, {@code false} otherwise.
      */
     public boolean hasChanged() {
         return changed;
     }
 
     /**
-     * If <code>hasChanged()</code> returns true, calls the
-     * <code>update()</code> method for every Observer in the list of
-     * observers using null as the argument. Afterwards calls
-     * <code>clearChanged()</code>.
-     * 
-     * Equivalent to calling <code>notifyObservers(null)</code>
+     * If {@code hasChanged()} returns {@code true}, calls the {@code update()}
+     * method for every observer in the list of observers using null as the
+     * argument. Afterwards, calls {@code clearChanged()}.
+     * <p>
+     * Equivalent to calling {@code notifyObservers(null)}.
      */
     public void notifyObservers() {
         notifyObservers(null);
     }
 
     /**
-     * If <code>hasChanged()</code> returns true, calls the
-     * <code>update()</code> method for every Observer in the list of
-     * observers using the specified argument. Afterwards calls
-     * <code>clearChanged()</code>.
+     * If {@code hasChanged()} returns {@code true}, calls the {@code update()}
+     * method for every Observer in the list of observers using the specified
+     * argument. Afterwards calls {@code clearChanged()}.
      * 
      * @param data
-     *            the argument passed to update()
+     *            the argument passed to {@code update()}.
      */
     @SuppressWarnings("unchecked")
     public void notifyObservers(Object data) {
@@ -136,9 +142,8 @@
     }
 
     /**
-     * Sets the changed flag for this Observable. After calling
-     * <code>setChanged()</code>, <code>hasChanged()</code> will return
-     * true.
+     * Sets the changed flag for this {@code Observable}. After calling
+     * {@code setChanged()}, {@code hasChanged()} will return {@code true}.
      */
     protected void setChanged() {
         changed = true;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observer.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Observer.java Thu May  7 21:43:41 2009
@@ -17,20 +17,24 @@
 
 package java.util;
 
+
 /**
- * Observer must be implemented by objects which are added to an Observable.
+ * {@code Observer} is the interface to be implemented by objects that 
+ * receive notification of updates on an {@code Observable} object.
+ * 
+ * @see Observable 
  */
 public interface Observer {
 
     /**
-     * When the specified observable object's <code>notifyObservers</code>
-     * method is called and the observable object has changed, this method is
-     * called.
+     * This method is called if the specified {@code Observable} object's
+     * {@code notifyObservers} method is called (because the {@code Observable} 
+     * object has been updated.
      * 
      * @param observable
-     *            the observable object
+     *            the {@link Observable} object.
      * @param data
-     *            the data passed to <code>notifyObservers</code>
+     *            the data passed to {@link Observable#notifyObservers(Object)}.
      */
     void update(Observable observable, Object data);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PriorityQueue.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PriorityQueue.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PriorityQueue.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PriorityQueue.java Thu May  7 21:43:41 2009
@@ -21,16 +21,16 @@
 import java.io.Serializable;
 
 /**
- * PriorityQueue holds elements on a priority heap, which orders elements
- * according to the comparator specified at construction or their natural order.
- * If the queue uses natural order, any element that is not comparable is not
- * permitted to insert to the queue.
- * 
+ * A PriorityQueue holds elements on a priority heap, which orders the elements
+ * according to their natural order or according to the comparator specified at
+ * construction time. If the queue uses natural ordering, only elements that are
+ * comparable are permitted to be inserted into the queue.
+ * <p>
  * The least element of the specified ordering is stored at the head of the
  * queue and the greatest element is stored at the tail of the queue.
- * 
- * PriorityQueue is not synchronized. If multiple threads will access it
- * concurrently, use the PriorityBlockingQueue.
+ * <p>
+ * A PriorityQueue is not synchronized. If multiple threads will have to access
+ * it concurrently, use the {@link java.util.concurrent.PriorityBlockingQueue}.
  */
 public class PriorityQueue<E> extends AbstractQueue<E> implements Serializable {
 
@@ -49,29 +49,36 @@
     private transient E[] elements;
 
     /**
-     * Constructs a priority queue with the capacity of 11 and natural ordering.
+     * Constructs a priority queue with an initial capacity of 11 and natural
+     * ordering.
      */
     public PriorityQueue() {
         this(DEFAULT_CAPACITY);
     }
 
     /**
-     * Constructs a priority queue with specified capacity and natural ordering.
+     * Constructs a priority queue with the specified capacity and natural
+     * ordering.
      * 
-     * @param initialCapacity the specified capacity.
-     * @throws IllegalArgumentException if the initialCapacity is less than 1
+     * @param initialCapacity
+     *            the specified capacity.
+     * @throws IllegalArgumentException
+     *             if the initialCapacity is less than 1.
      */
     public PriorityQueue(int initialCapacity) {
         this(initialCapacity, null);
     }
 
     /**
-     * Constructs a priority queue with specified capacity and comparator.
+     * Constructs a priority queue with the specified capacity and comparator.
      * 
-     * @param initialCapacity the specified capacity.
-     * @param comparator the specified comparator. If it is null, the natural
-     *        ordering will be used.
-     * @throws IllegalArgumentException if the initialCapacity is less than 1
+     * @param initialCapacity
+     *            the specified capacity.
+     * @param comparator
+     *            the specified comparator. If it is null, the natural ordering
+     *            will be used.
+     * @throws IllegalArgumentException
+     *             if the initialCapacity is less than 1.
      */
     public PriorityQueue(int initialCapacity, Comparator<? super E> comparator) {
         if (initialCapacity < 1) {
@@ -83,16 +90,17 @@
 
     /**
      * Constructs a priority queue that contains the elements of a collection.
-     * The constructed priority queue has the initial capacity of 110% the
-     * collection. And the priority queue uses natural ordering to order its
+     * The constructed priority queue has the initial capacity of 110% of the
+     * size of the collection. The queue uses natural ordering to order its
      * elements.
      * 
-     * @param c the collection whose elements will be added to the priority
-     *        queue to be constructed.
-     * @throws ClassCastException if any of the elements in the collection is
-     *         not comparable.
-     * @throws NullPointerException if any of the elements in the collection is
-     *         null.
+     * @param c
+     *            the collection whose elements will be added to the priority
+     *            queue to be constructed.
+     * @throws ClassCastException
+     *             if any of the elements in the collection are not comparable.
+     * @throws NullPointerException
+     *             if any of the elements in the collection are null.
      */
     public PriorityQueue(Collection<? extends E> c) {
         if (c instanceof PriorityQueue) {
@@ -108,11 +116,12 @@
     /**
      * Constructs a priority queue that contains the elements of another
      * priority queue. The constructed priority queue has the initial capacity
-     * of 110% the latter one. And the two priority queue has the same
+     * of 110% of the specified one. Both priority queues have the same
      * comparator.
      * 
-     * @param c the priority queue whose elements will be added to the priority
-     *        queue to be constructed.
+     * @param c
+     *            the priority queue whose elements will be added to the
+     *            priority queue to be constructed.
      */
     public PriorityQueue(PriorityQueue<? extends E> c) {
         getFromPriorityQueue(c);
@@ -120,12 +129,13 @@
 
     /**
      * Constructs a priority queue that contains the elements of a sorted set.
-     * The constructed priority queue has the initial capacity of 110% the
-     * sorted set. And the priority queue has the same comparator of the sorted
-     * set.
-     * 
-     * @param c the sorted set whose elements will be added to the priority
-     *        queue to be constructed.
+     * The constructed priority queue has the initial capacity of 110% of the
+     * size of the sorted set. The priority queue will have the same comparator
+     * as the sorted set.
+     * 
+     * @param c
+     *            the sorted set whose elements will be added to the priority
+     *            queue to be constructed.
      */
     public PriorityQueue(SortedSet<? extends E> c) {
         getFromSortedSet(c);
@@ -165,11 +175,14 @@
     /**
      * Inserts the element to the priority queue.
      * 
-     * @return true
-     * @throws ClassCastException if the element cannot be compared with the
-     *         elements in the priority queue using the ordering of the priority
-     *         queue.
-     * @throws NullPointerException if the element is null.
+     * @param o
+     *            the element to add to the priority queue.
+     * @return always true
+     * @throws ClassCastException
+     *             if the element cannot be compared with the elements in the
+     *             priority queue using the ordering of the priority queue.
+     * @throws NullPointerException
+     *             if {@code o} is {@code null}.
      */
     public boolean offer(E o) {
         if (null == o) {
@@ -184,7 +197,7 @@
     /**
      * Gets and removes the head of the queue.
      * 
-     * @return the head of the queue. Null if the queue is empty.
+     * @return the head of the queue or null if the queue is empty.
      */
     public E poll() {
         if (isEmpty()) {
@@ -196,9 +209,9 @@
     }
 
     /**
-     * Gets but not removes the head of the queue.
+     * Gets but does not remove the head of the queue.
      * 
-     * @return the head of the queue. Null if the queue is empty.
+     * @return the head of the queue or null if the queue is empty.
      */
     public E peek() {
         if (isEmpty()) {
@@ -210,7 +223,7 @@
     /**
      * Gets the comparator of the priority queue.
      * 
-     * @return the comparator of the priority queue. Null if the natural
+     * @return the comparator of the priority queue or null if the natural
      *         ordering is used.
      */
     public Comparator<? super E> comparator() {
@@ -218,11 +231,12 @@
     }
 
     /**
-     * Removes the specified object of the priority queue.
+     * Removes the specified object from the priority queue.
      * 
-     * @param o the object to be removed.
-     * @return true if the object is in the priority queue, false if the object
-     *         is not in the priority queue.
+     * @param o
+     *            the object to be removed.
+     * @return true if the object was in the priority queue, false if the object
+     *         was not in the priority queue.
      */
     @Override
     @SuppressWarnings("unchecked")
@@ -246,12 +260,14 @@
     /**
      * Adds the specified object to the priority queue.
      * 
-     * @param o the object to be added.
-     * @return true.
-     * @throws ClassCastException if the element cannot be compared with the
-     *         elements in the priority queue using the ordering of the priority
-     *         queue.
-     * @throws NullPointerException if the element is null.
+     * @param o
+     *            the object to be added.
+     * @return always true.
+     * @throws ClassCastException
+     *             if the element cannot be compared with the elements in the
+     *             priority queue using the ordering of the priority queue.
+     * @throws NullPointerException
+     *             if {@code o} is {@code null}.
      */
     @Override
     public boolean add(E o) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Properties.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Properties.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Properties.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Properties.java Thu May  7 21:43:41 2009
@@ -48,10 +48,12 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * Properties is a Hashtable where the keys and values must be Strings. Each
- * Properties can have a default Properties which specifies the default values
- * which are used if the key is not in this Properties.
- * 
+ * A {@code Properties} object is a {@code Hashtable} where the keys and values
+ * must be {@code String}s. Each property can have a default
+ * {@code Properties} list which specifies the default
+ * values to be used when a given key is not found in this {@code Properties}
+ * instance.
+ *
  * @see Hashtable
  * @see java.lang.System#getProperties
  */
@@ -71,7 +73,8 @@
             + "    <!ATTLIST entry key CDATA #REQUIRED >";
 
     /**
-     * The default values for this Properties.
+     * The default values for keys not found in this {@code Properties}
+     * instance.
      */
     protected Properties defaults;
 
@@ -79,18 +82,18 @@
             KEY_DONE = 4, IGNORE = 5;
 
     /**
-     * Constructs a new Properties object.
+     * Constructs a new {@code Properties} object.
      */
     public Properties() {
         super();
     }
 
     /**
-     * Constructs a new Properties object using the specified default
-     * properties.
+     * Constructs a new {@code Properties} object using the specified default
+     * {@code Properties}.
      * 
      * @param properties
-     *            the default properties
+     *            the default {@code Properties}.
      */
     public Properties(Properties properties) {
         defaults = properties;
@@ -138,12 +141,12 @@
 
     /**
      * Searches for the property with the specified name. If the property is not
-     * found, look in the default properties. If the property is not found in
-     * the default properties, answer null.
+     * found, the default {@code Properties} are checked. If the property is not
+     * found in the default {@code Properties}, {@code null} is returned.
      * 
      * @param name
-     *            the name of the property to find
-     * @return the named property value
+     *            the name of the property to find.
+     * @return the named property value, or {@code null} if it can't be found.
      */
     public String getProperty(String name) {
         Object result = super.get(name);
@@ -156,14 +159,15 @@
 
     /**
      * Searches for the property with the specified name. If the property is not
-     * found, look in the default properties. If the property is not found in
-     * the default properties, answer the specified default.
+     * found, it looks in the default {@code Properties}. If the property is not
+     * found in the default {@code Properties}, it returns the specified
+     * default.
      * 
      * @param name
-     *            the name of the property to find
+     *            the name of the property to find.
      * @param defaultValue
-     *            the default value
-     * @return the named property value
+     *            the default value.
+     * @return the named property value.
      */
     public String getProperty(String name, String defaultValue) {
         Object result = super.get(name);
@@ -178,11 +182,13 @@
     }
 
     /**
-     * Lists the mappings in this Properties to the specified PrintStream in a
+     * Lists the mappings in this {@code Properties} to the specified
+     * {@code PrintStream} in a
      * human readable form.
      * 
      * @param out
-     *            the PrintStream
+     *            the {@code PrintStream} to write the content to in human readable
+     *            form.
      */
     public void list(PrintStream out) {
         if (out == null) {
@@ -212,11 +218,13 @@
     }
 
     /**
-     * Lists the mappings in this Properties to the specified PrintWriter in a
+     * Lists the mappings in this {@code Properties} to the specified
+     * {@code PrintWriter} in a
      * human readable form.
      * 
      * @param writer
-     *            the PrintWriter
+     *            the {@code PrintWriter} to write the content to in human
+     *            readable form.
      */
     public void list(PrintWriter writer) {
         if (writer == null) {
@@ -246,12 +254,31 @@
     }
 
     /**
-     * Loads properties from the specified InputStream. The properties are of
-     * the form <code>key=value</code>, one property per line.
+     * Loads properties from the specified {@code InputStream}. The encoding is
+     * ISO8859-1. The {@code Properties} file is interpreted according to the
+     * following rules:
+     * <ul>
+     * <li>Empty lines are ignored.</li>
+     * <li>Lines starting with either a "#" or a "!" are comment lines and are
+     * ignored.</li>
+     * <li>A backslash at the end of the line escapes the following newline
+     * character ("\r", "\n", "\r\n"). If there's a whitespace after the
+     * backslash it will just escape that whitespace instead of concatenating
+     * the lines. This does not apply to comment lines.</li>
+     * <li>A property line consists of the key, the space between the key and
+     * the value, and the value. The key goes up to the first whitespace, "=" or
+     * ":" that is not escaped. The space between the key and the value contains
+     * either one whitespace, one "=" or one ":" and any number of additional
+     * whitespaces before and after that character. The value starts with the
+     * first character after the space between the key and the value.</li>
+     * <li>Following escape sequences are recognized: "\ ", "\\", "\r", "\n",
+     * "\!", "\#", "\t", "\b", "\f", and "&#92;uXXXX" (unicode character).</li>
+     * </ul>
      * 
      * @param in
-     *            the input stream
+     *            the {@code InputStream}.
      * @throws IOException
+     *             if error occurs during reading from the {@code InputStream}.
      */
     @SuppressWarnings("fallthrough")
     public synchronized void load(InputStream in) throws IOException {
@@ -421,9 +448,11 @@
     }
 
     /**
-     * Answers all of the property names that this Properties contains.
+     * Returns all of the property names that this {@code Properties} object
+     * contains.
      * 
-     * @return an Enumeration containing the names of all properties
+     * @return an {@code Enumeration} containing the names of all properties
+     *         that this {@code Properties} object contains.
      */
     public Enumeration<?> propertyNames() {
         if (defaults == null) {
@@ -445,19 +474,18 @@
     }
 
     /**
-     * Saves the mappings in this Properties to the specified OutputStream,
-     * putting the specified comment at the beginning. The output from this
-     * method is suitable for being read by the load() method.
-     * 
-     * @param out
-     *            the OutputStream
-     * @param comment
-     *            the comment
-     * 
-     * @exception ClassCastException
-     *                when the key or value of a mapping is not a String
-     * 
-     * @deprecated Does not throw an IOException, use store()
+     * Saves the mappings in this {@code Properties} to the specified {@code
+     * OutputStream}, putting the specified comment at the beginning. The output
+     * from this method is suitable for being read by the
+     * {@link #load(InputStream)} method.
+     * 
+     * @param out the {@code OutputStream} to write to.
+     * @param comment the comment to add at the beginning.
+     * @throws ClassCastException if the key or value of a mapping is not a
+     *                String.
+     * @deprecated This method ignores any {@code IOException} thrown while
+     *             writing -- use {@link #store} instead for better exception
+     *             handling.
      */
     @Deprecated
     public void save(OutputStream out, String comment) {
@@ -469,13 +497,13 @@
 
     /**
      * Maps the specified key to the specified value. If the key already exists,
-     * the old value is replaced. The key and value cannot be null.
+     * the old value is replaced. The key and value cannot be {@code null}.
      * 
      * @param name
-     *            the key
+     *            the key.
      * @param value
-     *            the value
-     * @return the old value mapped to the key, or null
+     *            the value.
+     * @return the old value mapped to the key, or {@code null}.
      */
     public Object setProperty(String name, String value) {
         return put(name, value);
@@ -484,18 +512,17 @@
     private static String lineSeparator;
 
     /**
-     * Stores the mappings in this Properties to the specified OutputStream,
-     * putting the specified comment at the beginning. The output from this
-     * method is suitable for being read by the load() method.
-     * 
-     * @param out
-     *            the OutputStream
-     * @param comment
-     *            the comment
-     * @throws IOException
-     * 
-     * @exception ClassCastException
-     *                when the key or value of a mapping is not a String
+     * Stores the mappings in this {@code Properties} to the specified {@code
+     * OutputStream}, putting the specified comment at the beginning. The output
+     * from this method is suitable for being read by the
+     * {@link #load(InputStream)} method.
+     * 
+     * @param out the {@code OutputStream} to write to.
+     * @param comment the comment to put at the beginning.
+     * @throws IOException if an error occurs during the write to the {@code
+     *             OutputStream}.
+     * @throws ClassCastException if the key or value of a mapping is not a
+     *                {@code String}.
      */
     public synchronized void store(OutputStream out, String comment)
             throws IOException {
@@ -527,6 +554,24 @@
         writer.flush();
     }
 
+    /**
+     * Loads the properties from an {@code InputStream} containing the
+     * properties in XML form. The XML document must begin with (and conform to)
+     * following DOCTYPE:
+     *
+     * <pre>
+     * &lt;!DOCTYPE properties SYSTEM &quot;http://java.sun.com/dtd/properties.dtd&quot;&gt;
+     * </pre>
+     *
+     * Also the content of the XML data must satisfy the DTD but the xml is not
+     * validated against it. The DTD is not loaded from the SYSTEM ID. After
+     * this method returns the InputStream is not closed.
+     *
+     * @param in the InputStream containing the XML document.
+     * @throws IOException in case an error occurs during a read operation.
+     * @throws InvalidPropertiesFormatException if the XML data is not a valid
+     *             properties file.
+     */
     public synchronized void loadFromXML(InputStream in) throws IOException,
             InvalidPropertiesFormatException {
         if (in == null) {
@@ -599,10 +644,45 @@
         }
     }
 
+    /**
+     * Writes all properties stored in this instance into the {@code
+     * OutputStream} in XML representation. The DOCTYPE is
+     *
+     * <pre>
+     * &lt;!DOCTYPE properties SYSTEM &quot;http://java.sun.com/dtd/properties.dtd&quot;&gt;
+     * </pre>
+     *
+     * If the comment is null, no comment is added to the output. UTF-8 is used
+     * as the encoding. The {@code OutputStream} is not closed at the end. A
+     * call to this method is the same as a call to {@code storeToXML(os,
+     * comment, "UTF-8")}.
+     *
+     * @param os the {@code OutputStream} to write to.
+     * @param comment the comment to add. If null, no comment is added.
+     * @throws IOException if an error occurs during writing to the output.
+     */
     public void storeToXML(OutputStream os, String comment) throws IOException {
         storeToXML(os, comment, "UTF-8"); //$NON-NLS-1$
     }
 
+    /**
+     * Writes all properties stored in this instance into the {@code
+     * OutputStream} in XML representation. The DOCTYPE is
+     *
+     * <pre>
+     * &lt;!DOCTYPE properties SYSTEM &quot;http://java.sun.com/dtd/properties.dtd&quot;&gt;
+     * </pre>
+     *
+     * If the comment is null, no comment is added to the output. The parameter
+     * {@code encoding} defines which encoding should be used. The {@code
+     * OutputStream} is not closed at the end.
+     *
+     * @param os the {@code OutputStream} to write to.
+     * @param comment the comment to add. If null, no comment is added.
+     * @param encoding the code identifying the encoding that should be used to
+     *            write into the {@code OutputStream}.
+     * @throws IOException if an error occurs during writing to the output.
+     */
     public synchronized void storeToXML(OutputStream os, String comment,
             String encoding) throws IOException {
 

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermission.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermission.java Thu May  7 21:43:41 2009
@@ -28,7 +28,17 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * PropertyPermission objects represent permission to access system properties.
+ * {@code PropertyPermission} objects represent a permission to access system
+ * properties.
+ * <p>
+ * A permission is one of the possible permission strings like "user.name" or
+ * "java.version". It's also possible to use a wildcard to define the permission
+ * to several properties at once. For example "user.*" will define the
+ * permission for "user.home", "user.name", "user.dir", ... "*" defines the
+ * permission for all available properties.
+ * <p>
+ * There are two possible permission action types: read and write. Possible
+ * actions are "read", "write", or "read,write"/"write,read".
  */
 public final class PropertyPermission extends BasicPermission {
     private static final long serialVersionUID = 885438825399942851L;
@@ -39,10 +49,11 @@
      * Constructs a new instance of this class.
      * 
      * @param name
-     *            java.lang.String the (possibly wildcarded) name of the
-     *            property.
+     *            the (possibly wildcarded) name of the property.
      * @param actions
-     *            java.lang.String the actions which are applicable to it.
+     *            the actions which are applicable to it. Possible actions are
+     *            "read", "write", or "read,write"/"write,read". Anything else
+     *            will result in an {@code IllegalArgumentException}.
      */
     public PropertyPermission(String name, String actions) {
         super(name);
@@ -68,15 +79,17 @@
     }
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
+     * Compares the argument to the receiver, and returns true if they represent
      * the <em>same</em> object using a class specific comparison. In this
-     * case, the receiver must be for the same property as the argument, and
-     * must have the same actions.
-     * 
+     * case, the receiver must be a {@code PropertyPermission} for the same
+     * property as the argument, and must have the same actions.
+     * If {@code o} is a permission that is not a {@code PropertyPermission},
+     * this method may throw a {@code ClassCastException}.
+     *
      * @param o
-     *            the object to compare with this object
-     * @return <code>true</code> if the object is the same as this object
-     *         <code>false</code> if it is different from this object
+     *            the {@code Object} to compare with this {@code Object}.
+     * @return {@code true} if the {@code Object} is the same as this {@code Object},
+     *         {@code false} if it is different from this {@code Object}.
      * @see #hashCode
      */
     @Override
@@ -89,10 +102,10 @@
     }
 
     /**
-     * Answers the actions associated with the receiver. The result will be
+     * Returns the actions associated with the receiver. The result will be
      * either "read", "write", or "read,write".
      * 
-     * @return String the actions associated with the receiver.
+     * @return the actions associated with the receiver.
      */
     @Override
     public String getActions() {
@@ -100,12 +113,11 @@
     }
 
     /**
-     * Answers an integer hash code for the receiver. Any two objects which
-     * answer <code>true</code> when passed to <code>equals</code> must
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
+     * Returns an integer hash code for the receiver. Any two objects which
+     * return {@code true} when passed to {@code equals} must return the same
+     * value for this method.
      * 
+     * @return the receiver's hash.
      * @see #equals
      */
     @Override
@@ -116,10 +128,10 @@
     /**
      * Indicates whether the argument permission is implied by the receiver.
      * 
-     * @return boolean <code>true</code> if the argument permission is implied
-     *         by the receiver, and <code>false</code> if it is not.
+     * @return boolean {@code true} if the argument permission is implied by the
+     *         receiver, and {@code false} if it is not.
      * @param permission
-     *            java.security.Permission the permission to check
+     *            the permission to check.
      */
     @Override
     public boolean implies(Permission permission) {
@@ -131,12 +143,11 @@
     }
 
     /**
-     * Answers a new PermissionCollection for holding permissions of this class.
-     * Answer null if any permission collection can be used.
-     * 
-     * @return a new PermissionCollection or null
+     * Returns a new {@code PermissionCollection} for holding permissions of this class.
+     * Returns {@code null} if any {@code PermissionCollection} can be used.
      * 
-     * see java.security.BasicPermissionCollection
+     * @return a new {@code PermissionCollection} or {@code null}.
+     * @see java.security.PermissionCollection
      */
     @Override
     public PermissionCollection newPermissionCollection() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermissionCollection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermissionCollection.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermissionCollection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyPermissionCollection.java Thu May  7 21:43:41 2009
@@ -25,7 +25,7 @@
 import java.security.PermissionCollection;
 
 /**
- * A PermissionCollection for holding PropertyPermissions.
+ * A {@code PermissionCollection} for holding {@code PropertyPermission}s.
  */
 class PropertyPermissionCollection extends PermissionCollection {
 

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyResourceBundle.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyResourceBundle.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyResourceBundle.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/PropertyResourceBundle.java Thu May  7 21:43:41 2009
@@ -21,9 +21,9 @@
 import java.io.InputStream;
 
 /**
- * PropertyResourceBundle loads resources from an InputStream. All resources are
- * Strings. The resources must be of the form <code>key=value</code>, one
- * resource per line.
+ * {@code PropertyResourceBundle} loads resources from an {@code InputStream}. All resources are
+ * Strings. The resources must be of the form {@code key=value}, one
+ * resource per line (see Properties).
  * 
  * @see ResourceBundle
  * @see Properties
@@ -34,12 +34,14 @@
     Properties resources;
 
     /**
-     * Constructs a new instance of PropertyResourceBundle and loads the
-     * properties file from the specified input stream.
+     * Constructs a new instance of {@code PropertyResourceBundle} and loads the
+     * properties file from the specified {@code InputStream}.
      * 
      * @param stream
-     *            the input stream
+     *            the {@code InputStream}.
      * @throws IOException
+     *             if an error occurs during a read operation on the
+     *             {@code InputStream}.
      */
     public PropertyResourceBundle(InputStream stream) throws IOException {
         resources = new Properties();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Queue.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Queue.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Queue.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Queue.java Thu May  7 21:43:41 2009
@@ -17,70 +17,72 @@
 package java.util;
 
 /**
- * A kind of collection provides advanced operations than other basic
+ * This kind of collection provides advanced operations compared to basic
  * collections, such as insertion, extraction, and inspection.
- * 
- * Generally, a queue orders its elements by means of first-in-first-out. While
- * priority queue orders its elements according to a comparator specified or the
- * elements' natural order. Furthermore, a stack orders its elements
- * last-in-first out.
- * 
- * A typical queue does not allow null to be inserted as its element, while some
- * implementations such as LinkedList allow it. But null should not be inserted
- * even in these implementations, since method poll return null to indicate that
- * there is no element left in the queue.
- * 
- * Queue does not provide blocking queue methods, which will block until the
- * operation of the method is allowed. BlockingQueue interface defines such
- * methods.
+ * <p>
+ * Generally, a queue orders its elements by means of first-in-first-out.
+ * However, a priority queue orders its elements according to a comparator
+ * specified or the elements' natural order. Furthermore, a stack orders its
+ * elements last-in-first out.
+ * <p>
+ * A typical queue does not allow {@code null} to be inserted as its element,
+ * while some implementations such as {@code LinkedList} allow it. But {@code
+ * null} should not be inserted even in these implementations, since the method
+ * {@code poll} returns {@code null} to indicate that there is no element left
+ * in the queue.
+ * <p>
+ * {@code Queue} does not provide blocking queue methods, which would block
+ * until the operation of the method is allowed. See the
+ * {@link java.util.concurrent.BlockingQueue} interface for information about
+ * blocking queue methods.
  */
 public interface Queue<E> extends Collection<E> {
 
     /**
      * Inserts the specified element into the queue provided that the condition
-     * allows such an operation. The method is generally preferable to the
-     * collection.add(E), since the latter might throw an exception if the
+     * allows such an operation. The method is generally preferable to
+     * {@link Collection#add}, since the latter might throw an exception if the
      * operation fails.
      * 
      * @param o
      *            the specified element to insert into the queue.
-     * @return true if the operation succeeds and false if it fails.
+     * @return {@code true} if the operation succeeds and {@code false} if it
+     *         fails.
      */
     public boolean offer(E o);
 
     /**
-     * Gets and removes the element in the head of the queue, or returns null if
-     * there is no element in the queue.
+     * Gets and removes the element at the head of the queue, or returns {@code
+     * null} if there is no element in the queue.
      * 
-     * @return the element in the head of the queue or null if there is no
-     *         element in the queue.
+     * @return the element at the head of the queue or {@code null} if there is
+     *         no element in the queue.
      */
     public E poll();
 
     /**
-     * Gets and removes the element in the head of the queue. Throws a
+     * Gets and removes the element at the head of the queue. Throws a
      * NoSuchElementException if there is no element in the queue.
      * 
-     * @return the element in the head of the queue.
+     * @return the element at the head of the queue.
      * @throws NoSuchElementException
      *             if there is no element in the queue.
      */
     public E remove();
 
     /**
-     * Gets but not removes the element in the head of the queue, or throws
-     * exception if there is no element in the queue.
+     * Gets but does not remove the element at the head of the queue.
      * 
-     * @return the element in the head of the queue or null if there is no
-     *         element in the queue.
+     * @return the element at the head of the queue or {@code null} if there is
+     *         no element in the queue.
      */
     public E peek();
 
     /**
-     * Gets but not removes the element in the head of the queue. Throws a
-     * NoSuchElementException if there is no element in the queue.
+     * Gets but does not remove the element at the head of the queue. Throws a
+     * {@code NoSuchElementException} if there is no element in the queue.
      * 
-     * @return the element in the head of the queue.
+     * @return the element at the head of the queue.
      * @throws NoSuchElementException
      *             if there is no element in the queue.
      */

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Random.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Random.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Random.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Random.java Thu May  7 21:43:41 2009
@@ -22,7 +22,7 @@
 
 /**
  * This class provides methods that generates pseudo-random numbers of different
- * types, such as int, long, double and float using either
+ * types, such as {@code int}, {@code long}, {@code double}, and {@code float}.
  * 
  * @see Properties
  * @see PropertyResourceBundle
@@ -63,13 +63,12 @@
     }
 
     /**
-     * Construct a random generator with the given <code>seed</code> as the
+     * Construct a random generator with the given {@code seed} as the
      * initial state.
      * 
      * @param seed
      *            the seed that will determine the initial state of this random
-     *            number generator
-     * 
+     *            number generator.
      * @see #setSeed
      */
     public Random(long seed) {
@@ -77,17 +76,14 @@
     }
 
     /**
-     * Returns a pseudo-random uniformly distributed <code>int</code> value of
-     * the number of bits specified by the argument <code>bits</code>.
-     * 
-     * Implements D. H. Lehmer's random number algorithm found in <i>The Art of
-     * Computer Programming, Volume 2: Seminumerical Algorithms</i>, by Donald
-     * E. Knuth (section 3.2.1).
+     * Returns a pseudo-random uniformly distributed {@code int} value of
+     * the number of bits specified by the argument {@code bits} as
+     * described by Donald E. Knuth in <i>The Art of Computer Programming,
+     * Volume 2: Seminumerical Algorithms</i>, section 3.2.1.
      * 
-     * @return a pseudo-randomly generated int
      * @param bits
-     *            number of bits of the returned value
-     * 
+     *            number of bits of the returned value.
+     * @return a pseudo-random generated int number.
      * @see #nextBytes
      * @see #nextDouble
      * @see #nextFloat
@@ -102,22 +98,21 @@
     }
 
     /**
-     * Answers the next pseudo-random, uniformly distributed boolean value
+     * Returns the next pseudo-random, uniformly distributed {@code boolean} value
      * generated by this generator.
      * 
-     * @return boolean a pseudo-random, uniformly distributed boolean value
+     * @return a pseudo-random, uniformly distributed boolean value.
      */
     public boolean nextBoolean() {
         return next(1) != 0;
     }
 
     /**
-     * Modifies the byte array by a random sequence of bytes generated by this
+     * Modifies the {@code byte} array by a random sequence of {@code byte}s generated by this
      * random number generator.
      * 
      * @param buf
-     *            non-null array to contain the new random bytes
-     * 
+     *            non-null array to contain the new random {@code byte}s.
      * @see #next
      */
     public void nextBytes(byte[] buf) {
@@ -135,11 +130,10 @@
     }
 
     /**
-     * Generates a normally distributed random double number between 0.0
+     * Generates a normally distributed random {@code double} number between 0.0
      * inclusively and 1.0 exclusively.
      * 
-     * @return a random double between 0.0 and 1.0
-     * 
+     * @return a random {@code double} in the range [0.0 - 1.0)
      * @see #nextFloat
      */
     public double nextDouble() {
@@ -147,11 +141,10 @@
     }
 
     /**
-     * Generates a normally distributed random float number between 0.0
+     * Generates a normally distributed random {@code float} number between 0.0
      * inclusively and 1.0 exclusively.
      * 
-     * @return a random float between 0.0 and 1.0
-     * 
+     * @return float a random {@code float} number between [0.0 and 1.0)
      * @see #nextDouble
      */
     public float nextFloat() {
@@ -159,16 +152,14 @@
     }
 
     /**
-     * Returns a pseudo-randomly generated, normally distributed
-     * <code>double</code> value with mean 0.0 and a standard deviation value
-     * of <code>1.0</code>.
-     * 
-     * Implements G. E. P. Box, M. E. Muller, and G. Marsaglia's polar method
-     * found in <i>The Art of Computer Programming, Volume 2: Seminumerical
-     * Algorithms</i>, by Donald E. Knuth (section 3.4.1).
-     * 
-     * @return a pseudo-randomly generated double
+     * Pseudo-randomly generates (approximately) a normally distributed
+     * {@code double} value with mean 0.0 and a standard deviation value
+     * of {@code 1.0} using the <i>polar method<i> of G. E. P. Box, M.
+     * E. Muller, and G. Marsaglia, as described by Donald E. Knuth in <i>The
+     * Art of Computer Programming, Volume 2: Seminumerical Algorithms</i>,
+     * section 3.4.1, subsection C, algorithm P.
      * 
+     * @return a random {@code double}
      * @see #nextDouble
      */
     public synchronized double nextGaussian() {
@@ -194,11 +185,10 @@
     }
 
     /**
-     * Generates a uniformly distributed 32-bit <code>int</code> value from
-     * the this random number sequence.
-     * 
-     * @return a randomly generated <code>int</code>
+     * Generates a uniformly distributed 32-bit {@code int} value from
+     * the random number sequence.
      * 
+     * @return a uniformly distributed {@code int} value.
      * @see java.lang.Integer#MAX_VALUE
      * @see java.lang.Integer#MIN_VALUE
      * @see #next
@@ -209,12 +199,12 @@
     }
 
     /**
-     * Returns a new pseudo-random integer value which is uniformly distributed
-     * between 0 (inclusively) and <code>n</code> (exclusively).
+     * Returns a new pseudo-random {@code int} value which is uniformly distributed
+     * between 0 (inclusively) and the value of {@code n} (exclusively).
      * 
-     * @return a randomly generated <code>int</code> between 0 and n
      * @param n
-     *            the upper limit of the values that can be returned
+     *            the exclusive upper border of the range [0 - n).
+     * @return a random {@code int}.
      */
     public int nextInt(int n) {
         if (n > 0) {
@@ -232,11 +222,10 @@
     }
 
     /**
-     * Generates a uniformly distributed 64-bit <code>int</code> value from
-     * the this random number sequence.
-     * 
-     * @return 64-bit <code>int</code> random number
+     * Generates a uniformly distributed 64-bit integer value from
+     * the random number sequence.
      * 
+     * @return 64-bit random integer.
      * @see java.lang.Integer#MAX_VALUE
      * @see java.lang.Integer#MIN_VALUE
      * @see #next
@@ -248,13 +237,11 @@
     }
 
     /**
-     * Modifies the seed using a linear congruential formula, as found in <i>The
-     * Art of Computer Programming, Volume 2</i>, by Donald E. Knuth (section
-     * 3.2.1).
+     * Modifies the seed a using linear congruential formula presented in <i>The
+     * Art of Computer Programming, Volume 2</i>, Section 3.2.1.
      * 
      * @param seed
-     *            the seed that alters the state of the random number generator
-     * 
+     *            the seed that alters the state of the random number generator.
      * @see #next
      * @see #Random()
      * @see #Random(long)

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/RandomAccess.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/RandomAccess.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/RandomAccess.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/RandomAccess.java Thu May  7 21:43:41 2009
@@ -18,8 +18,8 @@
 package java.util;
 
 /**
- * RandomAccess is implemented by <code>List</code> implementations that
- * support fast (usually constant time) random access.
+ * RandomAccess is implemented by {@code List} implementations that support fast
+ * (usually constant time) random access.
  */
 public interface RandomAccess {
     /* empty */

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ResourceBundle.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ResourceBundle.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ResourceBundle.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ResourceBundle.java Thu May  7 21:43:41 2009
@@ -26,20 +26,60 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * ResourceBundle is an abstract class which is the superclass of classes which
- * provide locale specific resources. A bundle contains a number of named
- * resources, where the names are Strings. A bundle may have a parent bundle,
- * when a resource is not found in a bundle, the parent bundle is searched for
- * the resource.
- * 
+ * {@code ResourceBundle} is an abstract class which is the superclass of classes which
+ * provide {@code Locale}-specific resources. A bundle contains a number of named
+ * resources, where the names are {@code Strings}. A bundle may have a parent bundle,
+ * and when a resource is not found in a bundle, the parent bundle is searched for
+ * the resource. If the fallback mechanism reaches the base bundle and still
+ * can't find the resource it throws a {@code MissingResourceException}.
+ *
+ * <ul>
+ * <li>All bundles for the same group of resources share a common base bundle.
+ * This base bundle acts as the root and is the last fallback in case none of
+ * its children was able to respond to a request.</li>
+ * <li>The first level contains changes between different languages. Only the
+ * differences between a language and the language of the base bundle need to be
+ * handled by a language-specific {@code ResourceBundle}.</li>
+ * <li>The second level contains changes between different countries that use
+ * the same language. Only the differences between a country and the country of
+ * the language bundle need to be handled by a country-specific {@code ResourceBundle}.
+ * </li>
+ * <li>The third level contains changes that don't have a geographic reason
+ * (e.g. changes that where made at some point in time like {@code PREEURO} where the
+ * currency of come countries changed. The country bundle would return the
+ * current currency (Euro) and the {@code PREEURO} variant bundle would return the old
+ * currency (e.g. DM for Germany).</li>
+ * </ul>
+ *
+ * <strong>Examples</strong>
+ * <ul>
+ * <li>BaseName (base bundle)
+ * <li>BaseName_de (german language bundle)
+ * <li>BaseName_fr (french language bundle)
+ * <li>BaseName_de_DE (bundle with Germany specific resources in german)
+ * <li>BaseName_de_CH (bundle with Switzerland specific resources in german)
+ * <li>BaseName_fr_CH (bundle with Switzerland specific resources in french)
+ * <li>BaseName_de_DE_PREEURO (bundle with Germany specific resources in german of
+ * the time before the Euro)
+ * <li>BaseName_fr_FR_PREEURO (bundle with France specific resources in french of
+ * the time before the Euro)
+ * </ul>
+ *
+ * It's also possible to create variants for languages or countries. This can be
+ * done by just skipping the country or language abbreviation:
+ * BaseName_us__POSIX or BaseName__DE_PREEURO. But it's not allowed to
+ * circumvent both language and country: BaseName___VARIANT is illegal.
+ *
  * @see Properties
  * @see PropertyResourceBundle
+ * @see ListResourceBundle
  * @since 1.1
  */
 public abstract class ResourceBundle {
 
     /**
-     * The parent of this ResourceBundle.
+     * The parent of this {@code ResourceBundle} that is used if this bundle doesn't
+     * include the requested resource.
      */
     protected ResourceBundle parent;
 
@@ -65,21 +105,20 @@
 
     /**
      * Constructs a new instance of this class.
-     * 
      */
     public ResourceBundle() {
         /* empty */
     }
 
     /**
-     * Finds the named resource bundle for the default locale.
+     * Finds the named resource bundle for the default {@code Locale} and the caller's
+     * {@code ClassLoader}.
      * 
      * @param bundleName
-     *            the name of the resource bundle
-     * @return ResourceBundle
-     * 
-     * @exception MissingResourceException
-     *                when the resource bundle cannot be found
+     *            the name of the {@code ResourceBundle}.
+     * @return the requested {@code ResourceBundle}.
+     * @throws MissingResourceException
+     *                if the {@code ResourceBundle} cannot be found.
      */
     public static final ResourceBundle getBundle(String bundleName)
             throws MissingResourceException {
@@ -88,16 +127,16 @@
     }
 
     /**
-     * Finds the named resource bundle for the specified locale.
+     * Finds the named {@code ResourceBundle} for the specified {@code Locale} and the caller
+     * {@code ClassLoader}.
      * 
      * @param bundleName
-     *            the name of the resource bundle
+     *            the name of the {@code ResourceBundle}.
      * @param locale
-     *            the locale
-     * @return ResourceBundle
-     * 
-     * @exception MissingResourceException
-     *                when the resource bundle cannot be found
+     *            the {@code Locale}.
+     * @return the requested resource bundle.
+     * @throws MissingResourceException
+     *                if the resource bundle cannot be found.
      */
     public static final ResourceBundle getBundle(String bundleName,
             Locale locale) {
@@ -105,18 +144,53 @@
     }
 
     /**
-     * Finds the named resource bundle for the specified locale.
+     * Finds the named resource bundle for the specified {@code Locale} and {@code ClassLoader}.
      * 
+     * The passed base name and {@code Locale} are used to create resource bundle names.
+     * The first name is created by concatenating the base name with the result
+     * of {@link Locale#toString()}. From this name all parent bundle names are
+     * derived. Then the same thing is done for the default {@code Locale}. This results
+     * in a list of possible bundle names.
+     *
+     * <strong>Example</strong> For the basename "BaseName", the {@code Locale} of the
+     * German part of Switzerland (de_CH) and the default {@code Locale} en_US the list
+     * would look something like this:
+     *
+     * <ol>
+     * <li>BaseName_de_CH</li>
+     * <li>BaseName_de</li>
+     * <li>Basename_en_US</li>
+     * <li>Basename_en</li>
+     * <li>BaseName</li>
+     * </ol>
+     *
+     * This list also shows the order in which the bundles will be searched for a requested
+     * resource in the German part of Switzerland (de_CH).
+     *
+     * As a first step, this method tries to instantiate
+     * a {@code ResourceBundle} with the names provided.
+     * If such a class can be instantiated and initialized, it is returned and
+     * all the parent bundles are instantiated too. If no such class can be
+     * found this method tries to load a {@code .properties} file with the names by
+     * replacing dots in the base name with a slash and by appending
+     * "{@code .properties}" at the end of the string. If such a resource can be found
+     * by calling {@link ClassLoader#getResource(String)} it is used to
+     * initialize a {@link PropertyResourceBundle}. If this succeeds, it will
+     * also load the parents of this {@code ResourceBundle}.
+     *
+     * For compatibility with older code, the bundle name isn't required to be
+     * a fully qualified class name. It's also possible to directly pass
+     * the path to a properties file (without a file extension).
+     *
      * @param bundleName
-     *            the name of the resource bundle
+     *            the name of the {@code ResourceBundle}.
      * @param locale
-     *            the locale
+     *            the {@code Locale}.
      * @param loader
-     *            the ClassLoader to use
-     * @return ResourceBundle
-     * 
-     * @exception MissingResourceException
-     *                when the resource bundle cannot be found
+     *            the {@code ClassLoader} to use.
+     * @return the requested {@code ResourceBundle}.
+     * @throws MissingResourceException
+     *                if the {@code ResourceBundle} cannot be found.
      */
     public static ResourceBundle getBundle(String bundleName, Locale locale,
             ClassLoader loader) throws MissingResourceException {
@@ -169,30 +243,34 @@
     }
 
     /**
-     * Answers the names of the resources contained in this ResourceBundle.
+     * Returns the names of the resources contained in this {@code ResourceBundle}.
      * 
-     * @return an Enumeration of the resource names
+     * @return an {@code Enumeration} of the resource names.
      */
     public abstract Enumeration<String> getKeys();
 
     /**
-     * Gets the Locale of this ResourceBundle.
+     * Gets the {@code Locale} of this {@code ResourceBundle}. In case a bundle was not
+     * found for the requested {@code Locale}, this will return the actual {@code Locale} of
+     * this resource bundle that was found after doing a fallback.
      * 
-     * @return the Locale of this ResourceBundle
+     * @return the {@code Locale} of this {@code ResourceBundle}.
      */
     public Locale getLocale() {
         return locale;
     }
 
     /**
-     * Answers the named resource from this ResourceBundle.
+     * Returns the named resource from this {@code ResourceBundle}. If the resource
+     * cannot be found in this bundle, it falls back to the parent bundle (if
+     * it's not null) by calling the {@link #handleGetObject} method. If the resource still
+     * can't be found it throws a {@code MissingResourceException}.
      * 
      * @param key
-     *            the name of the resource
-     * @return the resource object
-     * 
-     * @exception MissingResourceException
-     *                when the resource is not found
+     *            the name of the resource.
+     * @return the resource object.
+     * @throws MissingResourceException
+     *                if the resource is not found.
      */
     public final Object getObject(String key) {
         ResourceBundle last, theParent = this;
@@ -208,28 +286,32 @@
     }
 
     /**
-     * Answers the named resource from this ResourceBundle.
+     * Returns the named string resource from this {@code ResourceBundle}.
      * 
      * @param key
-     *            the name of the resource
-     * @return the resource string
-     * 
-     * @exception MissingResourceException
-     *                when the resource is not found
+     *            the name of the resource.
+     * @return the resource string.
+     * @throws MissingResourceException
+     *                if the resource is not found.
+     * @throws ClassCastException
+     *                if the resource found is not a string.
+     * @see #getObject(String)
      */
     public final String getString(String key) {
         return (String) getObject(key);
     }
 
     /**
-     * Answers the named resource from this ResourceBundle.
+     * Returns the named resource from this {@code ResourceBundle}.
      * 
      * @param key
-     *            the name of the resource
-     * @return the resource string array
-     * 
-     * @exception MissingResourceException
-     *                when the resource is not found
+     *            the name of the resource.
+     * @return the resource string array.
+     * @throws MissingResourceException
+     *                if the resource is not found.
+     * @throws ClassCastException
+     *                if the resource found is not an array of strings.
+     * @see #getObject(String)
      */
     public final String[] getStringArray(String key) {
         return (String[]) getObject(key);
@@ -328,21 +410,21 @@
     }
 
     /**
-     * Answers the named resource from this ResourceBundle, or null if the
+     * Returns the named resource from this {@code ResourceBundle}, or null if the
      * resource is not found.
      * 
      * @param key
-     *            the name of the resource
-     * @return the resource object
+     *            the name of the resource.
+     * @return the resource object.
      */
     protected abstract Object handleGetObject(String key);
 
     /**
-     * Sets the parent resource bundle of this ResourceBundle. The parent is
-     * searched for resources which are not found in this resource bundle.
+     * Sets the parent resource bundle of this {@code ResourceBundle}. The parent is
+     * searched for resources which are not found in this {@code ResourceBundle}.
      * 
      * @param bundle
-     *            the parent resource bundle
+     *            the parent {@code ResourceBundle}.
      */
     protected void setParent(ResourceBundle bundle) {
         parent = bundle;



Mime
View raw message