Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 77132 invoked from network); 7 May 2009 21:44:52 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 7 May 2009 21:44:52 -0000 Received: (qmail 67328 invoked by uid 500); 7 May 2009 21:44:52 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 67283 invoked by uid 500); 7 May 2009 21:44:52 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 67274 invoked by uid 99); 7 May 2009 21:44:52 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 07 May 2009 21:44:52 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 07 May 2009 21:44:37 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id A6ACD2388BB5; Thu, 7 May 2009 21:43:51 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r772785 [11/12] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ Date: Thu, 07 May 2009 21:43:44 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090507214351.A6ACD2388BB5@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java Thu May 7 21:43:41 2009 @@ -18,7 +18,7 @@ package java.util; /** - * The TimerTask class is represents a task to run at specified time. The task + * The {@code TimerTask} class represents a task to run at a specified time. The task * may be run once or repeatedly. * * @see Timer @@ -65,7 +65,7 @@ /* * Is TimerTask scheduled into any timer? * - * @return true if the timer task is scheduled, false + * @return {@code true} if the timer task is scheduled, {@code false} * otherwise. */ boolean isScheduled() { @@ -74,17 +74,20 @@ } } + /** + * Creates a new {@code TimerTask}. + */ protected TimerTask() { super(); } /** - * Cancels the Task and removes it from the Timer's queue. Generally, it - * returns false if the call did not prevent a TimerTask from running at + * Cancels the {@code TimerTask} and removes it from the {@code Timer}'s queue. Generally, it + * returns {@code false} if the call did not prevent a {@code TimerTask} from running at * least once. Subsequent calls have no effect. * - * @return true if the call prevented a scheduled execution - * from taking place, false otherwise. + * @return {@code true} if the call prevented a scheduled execution + * from taking place, {@code false} otherwise. */ public boolean cancel() { synchronized (lock) { @@ -96,8 +99,8 @@ /** * Returns the scheduled execution time. If the task execution is in - * progress returns the execution time of ongoing task. Tasks which have not - * yet run return an undefined value. + * progress it returns the execution time of the ongoing task. Tasks which + * have not yet run return an undefined value. * * @return the most recent execution time. */ @@ -108,7 +111,7 @@ } /** - * The task to run should be specified in the implementation of the run() + * The task to run should be specified in the implementation of the {@code run()} * method. */ public abstract void run(); Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java Thu May 7 21:43:41 2009 @@ -17,32 +17,33 @@ package java.util; + /** - * This exception is thrown when an attempt is made to add more than one - * listener to an event source which only supports a single listener. It is also - * thrown when the same listener is added more than once. - * - * @see java.lang.Exception + * A {@code TooManyListenersException} is thrown when an attempt is made to add + * more than one listener to an event source which only supports a single + * listener. It is also thrown when the same listener is added more than once. */ public class TooManyListenersException extends Exception { private static final long serialVersionUID = 5074640544770687831L; /** - * Constructs a new instance of this class with its walkback filled in. + * Constructs a new {@code TooManyListenersException} with the current stack + * trace filled in. */ public TooManyListenersException() { super(); } /** - * Constructs a new instance of this class with its walkback and message - * filled in. + * Constructs a new {@code TooManyListenersException} with the stack trace + * and message filled in. * * @param detailMessage - * String The detail message for the exception. + * the detail message for the exception. */ public TooManyListenersException(String detailMessage) { super(detailMessage); } + } Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java Thu May 7 21:43:41 2009 @@ -23,9 +23,9 @@ import java.io.Serializable; /** - * TreeMap is an implementation of SortedMap. All optional operations are - * supported, adding and removing. The values can be any objects. The keys can - * be any objects which are comparable to each other either using their natural + * TreeMap is an implementation of SortedMap. All optional operations (adding + * and removing) are supported. The values can be any objects. The keys can be + * any objects which are comparable to each other either using their natural * order or a specified Comparator. * * @since 1.2 @@ -958,38 +958,43 @@ } /** - * Constructs a new empty instance of spec.TreeMap. + * Constructs a new empty {@code TreeMap} instance. */ public TreeMap() { } /** - * Constructs a new empty instance of spec.TreeMap which uses the specified - * Comparator. + * Constructs a new empty {@code TreeMap} instance with the specified + * comparator. * - * @param comparator the Comparator + * @param comparator + * the comparator to compare keys with. */ public TreeMap(Comparator comparator) { this.comparator = comparator; } /** - * Constructs a new instance of spec.TreeMap containing the mappings from the - * specified Map and using the natural ordering. + * Constructs a new {@code TreeMap} instance containing the mappings from + * the specified map and using natural ordering. * - * @param map the mappings to add - * @throws ClassCastException when a key in the Map does not implement the Comparable - * interface, or they keys in the Map cannot be compared + * @param map + * the mappings to add. + * @throws ClassCastException + * if a key in the specified map does not implement the + * Comparable interface, or if the keys in the map cannot be + * compared. */ public TreeMap(Map map) { putAll(map); } /** - * Constructs a new instance of spec.TreeMap containing the mappings from the - * specified SortedMap and using the same Comparator. + * Constructs a new {@code TreeMap} instance containing the mappings from + * the specified SortedMap and using the same comparator. * - * @param map the mappings to add + * @param map + * the mappings to add. */ public TreeMap(SortedMap map) { this(map.comparator()); @@ -1019,10 +1024,10 @@ } /** - * Removes all mappings from this spec.TreeMap, leaving it empty. + * Removes all mappings from this TreeMap, leaving it empty. * - * @see Map#isEmpty - * @see #size + * @see Map#isEmpty() + * @see #size() */ @Override public void clear() { @@ -1032,10 +1037,10 @@ } /** - * Answers a new spec.TreeMap with the same mappings, size and comparator as this - * spec.TreeMap. + * Returns a new {@code TreeMap} with the same mappings, size and comparator + * as this instance. * - * @return a shallow copy of this spec.TreeMap + * @return a shallow copy of this instance. * @see java.lang.Cloneable */ @SuppressWarnings("unchecked") @@ -1077,23 +1082,27 @@ } /** - * Answers the Comparator used to compare elements in this spec.TreeMap. + * Returns the comparator used to compare elements in this map. * - * @return a Comparator or null if the natural ordering is used + * @return the comparator or {@code null} if the natural ordering is used. */ public Comparator comparator() { return comparator; } /** - * Searches this spec.TreeMap for the specified key. + * Returns whether this map contains the specified key. * - * @param key the object to search for - * @return true if key is a key of this spec.TreeMap, false - * otherwise - * @throws ClassCastException when the key cannot be compared with the keys in this - * spec.TreeMap - * @throws NullPointerException when the key is null and the comparator cannot handle null + * @param key + * the key to search for. + * @return {@code true} if this map contains the specified key, + * {@code false} otherwise. + * @throws ClassCastException + * if the specified key cannot be compared with the keys in this + * map. + * @throws NullPointerException + * if the specified key is {@code null} and the comparator + * cannot handle {@code null} keys. */ @Override public boolean containsKey(Object key) { @@ -1138,11 +1147,12 @@ } /** - * Searches this spec.TreeMap for the specified value. + * Returns whether this map contains the specified value. * - * @param value the object to search for - * @return true if value is a value of this spec.TreeMap, false - * otherwise + * @param value + * the value to search for. + * @return {@code true} if this map contains the specified value, + * {@code false} otherwise. */ @Override public boolean containsValue(Object value) { @@ -1177,11 +1187,12 @@ } /** - * Answers a Set of the mappings contained in this spec.TreeMap. Each element in - * the set is a Map.Entry. The set is backed by this spec.TreeMap so changes to - * one are reflected by the other. The set does not support adding. + * Returns a set containing all of the mappings in this map. Each mapping is + * an instance of {@link Map.Entry}. As the set is backed by this map, + * changes in one will be reflected in the other. It does not support adding + * operations. * - * @return a Set of the mappings + * @return a set of the mappings. */ @Override public Set> entrySet() { @@ -1230,10 +1241,11 @@ } /** - * Answers the first sorted key in this spec.TreeMap. + * Returns the first key in this map. * - * @return the first sorted key - * @throws NoSuchElementException when this spec.TreeMap is empty + * @return the first key in this map. + * @throws NoSuchElementException + * if this map is empty. */ public K firstKey() { if (root != null) { @@ -1245,13 +1257,16 @@ /** - * 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 - * @throws ClassCastException when the key cannot be compared with the keys in this - * spec.TreeMap - * @throws NullPointerException when the key is null and the comparator cannot handle null + * @param key + * the key. + * @return the value of the mapping with the specified key. + * @throws ClassCastException + * if the key cannot be compared with the keys in this map. + * @throws NullPointerException + * if the key is {@code null} and the comparator cannot handle + * {@code null}. */ @Override public V get(Object key) { @@ -1301,16 +1316,25 @@ } /** - * Answers a SortedMap of the specified portion of this spec.TreeMap which - * contains keys less than the end key. The returned SortedMap is backed by - * this spec.TreeMap so changes to one are reflected by the other. - * - * @param endKey the end key - * @return a sub-map where the keys are less than endKey - * @throws ClassCastException when the end key cannot be compared with the keys in this - * spec.TreeMap - * @throws NullPointerException when the end key is null and the comparator cannot handle - * null + * Returns a sorted map over a range of this sorted map with all keys that + * are less than the specified {@code endKey}. Changes to the returned + * sorted map are reflected in this sorted map and vice versa. + *

+ * Note: The returned map will not allow an insertion of a key outside the + * specified range. + * + * @param endKey + * the high boundary of the range specified. + * @return a sorted map where the keys are less than {@code endKey}. + * @throws ClassCastException + * if the specified key cannot be compared with the keys in this + * map. + * @throws NullPointerException + * if the specified key is {@code null} and the comparator + * cannot handle {@code null} keys. + * @throws IllegalArgumentException + * if this map is itself a sorted map over a range of another + * map and the specified key is outside of its range. */ public SortedMap headMap(K endKey) { // Check for errors @@ -1323,11 +1347,11 @@ } /** - * Answers a Set of the keys contained in this spec.TreeMap. The set is backed by - * this spec.TreeMap so changes to one are reflected by the other. The set does - * not support adding. + * Returns a set of the keys contained in this map. The set is backed by + * this map so changes to one are reflected by the other. The set does not + * support adding. * - * @return a Set of the keys + * @return a set of the keys. */ @Override public Set keySet() { @@ -1367,10 +1391,11 @@ } /** - * Answer the last sorted key in this spec.TreeMap. + * Returns the last key in this map. * - * @return the last sorted key - * @throws NoSuchElementException when this spec.TreeMap is empty + * @return the last key in this map. + * @throws NoSuchElementException + * if this map is empty. */ public K lastKey() { if (root != null) { @@ -1403,13 +1428,18 @@ /** * Maps the specified key to the specified value. * - * @param 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 - * @throws ClassCastException when the key cannot be compared with the keys in this - * spec.TreeMap - * @throws NullPointerException when the key is null and the comparator cannot handle null + * @param key + * the key. + * @param value + * the value. + * @return the value of any previous mapping with the specified key or + * {@code null} if there was no mapping. + * @throws ClassCastException + * if the specified key cannot be compared with the keys in this + * map. + * @throws NullPointerException + * if the specified key is {@code null} and the comparator + * cannot handle {@code null} keys. */ @Override public V put(K key, V value) { @@ -1776,13 +1806,18 @@ /** - * Copies every mapping in the specified Map to this spec.TreeMap. - * - * @param map the Map to copy mappings from - * @throws ClassCastException when a key in the Map cannot be compared with the keys in - * this spec.TreeMap - * @throws NullPointerException when a key in the Map is null and the comparator cannot - * handle null + * Copies all the mappings in the given map to this map. These mappings will + * replace all mappings that this map had for any of the keys currently in + * the given map. + * + * @param map + * the map to copy mappings from. + * @throws ClassCastException + * if a key in the specified map cannot be compared with the + * keys in this map. + * @throws NullPointerException + * if a key in the specified map is {@code null} and the + * comparator cannot handle {@code null} keys. */ @Override public void putAll(Map map) { @@ -1790,14 +1825,18 @@ } /** - * Removes a mapping with the specified key from this spec.TreeMap. + * Removes the mapping with the specified key from this map. * - * @param key the key of the mapping to remove - * @return the value of the removed mapping or null if key is not a key in - * this spec.TreeMap - * @throws ClassCastException when the key cannot be compared with the keys in this - * spec.TreeMap - * @throws NullPointerException when the key is null and the comparator cannot handle null + * @param key + * 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 ClassCastException + * if the specified key cannot be compared with the keys in this + * map. + * @throws NullPointerException + * if the specified key is {@code null} and the comparator + * cannot handle {@code null} keys. */ @Override public V remove(Object key) { @@ -2213,9 +2252,9 @@ /** - * Answers the number of mappings in this spec.TreeMap. + * Returns the number of mappings in this map. * - * @return the number of mappings in this spec.TreeMap + * @return the number of mappings in this map. */ @Override public int size() { @@ -2223,19 +2262,29 @@ } /** - * Answers a SortedMap of the specified portion of this spec.TreeMap which - * contains keys greater or equal to the start key but less than the end - * key. The returned SortedMap is backed by this spec.TreeMap so changes to one - * are reflected by the other. - * - * @param startKey the start key - * @param endKey the end key - * @return a sub-map where the keys are greater or equal to - * startKey and less than endKey - * @throws ClassCastException when the start or end key cannot be compared with the keys - * in this spec.TreeMap - * @throws NullPointerException when the start or end key is null and the comparator - * cannot handle null + * Returns a sorted map over a range of this sorted map with all keys + * greater than or equal to the specified {@code startKey} and less than the + * specified {@code endKey}. Changes to the returned sorted map are + * reflected in this sorted map and vice versa. + *

+ * Note: The returned map will not allow an insertion of a key outside the + * specified range. + * + * @param startKey + * the low boundary of the range (inclusive). + * @param endKey + * the high boundary of the range (exclusive), + * @return a sorted map with the key from the specified range. + * @throws ClassCastException + * if the start or end key cannot be compared with the keys in + * this map. + * @throws NullPointerException + * if the start or end key is {@code null} and the comparator + * cannot handle {@code null} keys. + * @throws IllegalArgumentException + * if the start key is greater than the end key, or if this map + * is itself a sorted map over a range of another sorted map and + * the specified range is outside of its range. */ public SortedMap subMap(K startKey, K endKey) { if (comparator == null) { @@ -2251,17 +2300,26 @@ } /** - * Answers a SortedMap of the specified portion of this spec.TreeMap which - * contains keys greater or equal to the start key. The returned SortedMap - * is backed by this spec.TreeMap so changes to one are reflected by the other. - * - * @param startKey the start key - * @return a sub-map where the keys are greater or equal to - * startKey - * @throws ClassCastException when the start key cannot be compared with the keys in - * this spec.TreeMap - * @throws NullPointerException when the start key is null and the comparator cannot - * handle null + * Returns a sorted map over a range of this sorted map with all keys that + * are greater than or equal to the specified {@code startKey}. Changes to + * the returned sorted map are reflected in this sorted map and vice versa. + *

+ * Note: The returned map will not allow an insertion of a key outside the + * specified range. + * + * @param startKey + * the low boundary of the range specified. + * @return a sorted map where the keys are greater or equal to + * {@code startKey}. + * @throws ClassCastException + * if the specified key cannot be compared with the keys in this + * map. + * @throws NullPointerException + * if the specified key is {@code null} and the comparator + * cannot handle {@code null} keys. + * @throws IllegalArgumentException + * if this map itself a sorted map over a range of another map + * and the specified key is outside of its range. */ public SortedMap tailMap(K startKey) { // Check for errors @@ -2274,11 +2332,23 @@ } /** - * Answers a Collection of the values contained in this spec.TreeMap. The - * collection is backed by this spec.TreeMap so changes to one are reflected by - * the other. The collection does not support adding. + * Returns a collection of the values contained in this map. The collection + * is backed by this map so changes to one are reflected by the other. The + * collection supports remove, removeAll, retainAll and clear operations, + * and it does not support add or addAll operations. + *

+ * This method returns a collection which is the subclass of + * AbstractCollection. The iterator method of this subclass returns a + * "wrapper object" over the iterator of map's entrySet(). The {@code size} + * method wraps the map's size method and the {@code contains} method wraps + * the map's containsValue method. + *

+ * The collection is created when this method is called for the first time + * and returned in response to all subsequent calls. This method may return + * different collections when multiple concurrent calls occur, since no + * synchronization is performed. * - * @return a Collection of the values + * @return a collection of the values contained in this map. */ @Override public Collection values() { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java Thu May 7 21:43:41 2009 @@ -23,8 +23,8 @@ import java.io.Serializable; /** - * TreeSet is an implementation of SortedSet. All optional operations are - * supported, adding and removing. The elements can be any objects which are + * TreeSet is an implementation of SortedSet. All optional operations (adding + * and removing) are supported. The elements can be any objects which are * comparable to each other either using their natural order or a specified * Comparator. * @@ -42,24 +42,23 @@ } /** - * Constructs a new empty instance of TreeSet which uses natural ordering. - * + * Constructs a new empty instance of {@code TreeSet} which uses natural + * ordering. */ public TreeSet() { backingMap = new TreeMap(); } /** - * Constructs a new instance of TreeSet which uses natural ordering and - * containing the unique elements in the specified collection. + * Constructs a new instance of {@code TreeSet} which uses natural ordering + * and containing the unique elements in the specified collection. * * @param collection - * the collection of elements to add - * - * @exception ClassCastException - * when an element in the Collection does not implement the - * Comparable interface, or the elements in the Collection - * cannot be compared + * the collection of elements to add. + * @throws ClassCastException + * when an element in the collection does not implement the + * Comparable interface, or the elements in the collection + * cannot be compared. */ public TreeSet(Collection collection) { this(); @@ -67,22 +66,22 @@ } /** - * Constructs a new empty instance of TreeSet which uses the specified - * Comparator. + * Constructs a new empty instance of {@code TreeSet} which uses the + * specified comparator. * * @param comparator - * the Comparator + * the comparator to use. */ public TreeSet(Comparator comparator) { backingMap = new TreeMap(comparator); } /** - * Constructs a new instance of TreeSet containing the elements in the - * specified SortedSet and using the same Comparator. + * Constructs a new instance of {@code TreeSet} containing the elements of + * the specified SortedSet and using the same Comparator. * * @param set - * the SortedSet of elements to add + * the SortedSet of elements to add. */ public TreeSet(SortedSet set) { this(set.comparator()); @@ -93,19 +92,18 @@ } /** - * Adds the specified object to this TreeSet. + * Adds the specified object to this {@code TreeSet}. * * @param object - * the object to add - * @return true when this TreeSet did not already contain the object, false - * otherwise - * - * @exception ClassCastException - * when the object cannot be compared with the elements in - * this TreeSet - * @exception NullPointerException - * when the object is null and the comparator cannot handle - * null + * the object to add. + * @return {@code true} when this {@code TreeSet} did not already contain + * the object, {@code false} otherwise. + * @throws ClassCastException + * when the object cannot be compared with the elements in this + * {@code TreeSet}. + * @throws NullPointerException + * when the object is null and the comparator cannot handle + * null. */ @Override public boolean add(E object) { @@ -113,18 +111,18 @@ } /** - * Adds the objects in the specified Collection to this TreeSet. + * Adds the objects in the specified collection to this {@code TreeSet}. * * @param collection - * the Collection of objects - * @return true if this TreeSet is modified, false otherwise - * - * @exception ClassCastException - * when an object in the Collection cannot be compared with - * the elements in this TreeSet - * @exception NullPointerException - * when an object in the Collection is null and the - * comparator cannot handle null + * the collection of objects to add. + * @return {@code true} if this {@code TreeSet} was modified, {@code false} + * otherwise. + * @throws ClassCastException + * when an object in the collection cannot be compared with the + * elements in this {@code TreeSet}. + * @throws NullPointerException + * when an object in the collection is null and the comparator + * cannot handle null. */ @Override public boolean addAll(Collection collection) { @@ -132,7 +130,7 @@ } /** - * Removes all elements from this TreeSet, leaving it empty. + * Removes all elements from this {@code TreeSet}, leaving it empty. * * @see #isEmpty * @see #size @@ -143,11 +141,10 @@ } /** - * Answers a new TreeSet with the same elements, size and comparator as this - * TreeSet. - * - * @return a shallow copy of this TreeSet + * Returns a new {@code TreeSet} with the same elements, size and comparator + * as this {@code TreeSet}. * + * @return a shallow copy of this {@code TreeSet}. * @see java.lang.Cloneable */ @SuppressWarnings("unchecked") @@ -168,7 +165,7 @@ } /** - * Answers the Comparator used to compare elements in this TreeSet. + * Returns the comparator used to compare elements in this {@code TreeSet}. * * @return a Comparator or null if the natural ordering is used */ @@ -177,19 +174,18 @@ } /** - * Searches this TreeSet for the specified object. + * Searches this {@code TreeSet} for the specified object. * * @param object - * the object to search for - * @return true if object is an element of this TreeSet, - * false otherwise - * - * @exception ClassCastException - * when the object cannot be compared with the elements in - * this TreeSet - * @exception NullPointerException - * when the object is null and the comparator cannot handle - * null + * the object to search for. + * @return {@code true} if {@code object} is an element of this + * {@code TreeSet}, {@code false} otherwise. + * @throws ClassCastException + * when the object cannot be compared with the elements in this + * {@code TreeSet}. + * @throws NullPointerException + * when the object is null and the comparator cannot handle + * null. */ @Override public boolean contains(Object object) { @@ -197,32 +193,31 @@ } /** - * Answers the first element in this TreeSet. - * - * @return the first element + * Returns the first element in this {@code TreeSet}. * - * @exception NoSuchElementException - * when this TreeSet is empty + * @return the first element. + * @throws NoSuchElementException + * when this {@code TreeSet} is empty. */ public E first() { return backingMap.firstKey(); } /** - * Answers a SortedSet of the specified portion of this TreeSet which - * contains elements less than the end element. The returned SortedSet is - * backed by this TreeSet so changes to one are reflected by the other. + * Returns a SortedSet of the specified portion of this {@code TreeSet} + * which contains elements which are all less than the end element. The + * returned SortedSet is backed by this {@code TreeSet} so changes to one + * are reflected by the other. * * @param end - * the end element - * @return a subset where the elements are less than end - * - * @exception ClassCastException - * when the end object cannot be compared with the elements - * in this TreeSet - * @exception NullPointerException - * when the end object is null and the comparator cannot - * handle null + * the end element. + * @return a subset where the elements are less than {@code end} + * @throws ClassCastException + * when the end object cannot be compared with the elements in + * this {@code TreeSet}. + * @throws NullPointerException + * when the end object is null and the comparator cannot handle + * null. */ @SuppressWarnings("unchecked") public SortedSet headSet(E end) { @@ -237,10 +232,9 @@ } /** - * Answers if this TreeSet has no elements, a size of zero. - * - * @return true if this TreeSet has no elements, false otherwise + * Returns true if this {@code TreeSet} has no element, otherwise false. * + * @return true if this {@code TreeSet} has no element. * @see #size */ @Override @@ -249,10 +243,9 @@ } /** - * Answers an Iterator on the elements of this TreeSet. - * - * @return an Iterator on the elements of this TreeSet + * Returns an Iterator on the elements of this {@code TreeSet}. * + * @return an Iterator on the elements of this {@code TreeSet}. * @see Iterator */ @Override @@ -261,30 +254,30 @@ } /** - * Answers the last element in this TreeSet. + * Returns the last element in this {@code TreeSet}. The last element is + * the highest element. * - * @return the last element - * - * @exception NoSuchElementException - * when this TreeSet is empty + * @return the last element. + * @throws NoSuchElementException + * when this {@code TreeSet} is empty. */ public E last() { return backingMap.lastKey(); } /** - * Removes an occurrence of the specified object from this TreeSet. + * Removes an occurrence of the specified object from this {@code TreeSet}. * * @param object - * the object to remove - * @return true if this TreeSet is modified, false otherwise - * - * @exception ClassCastException - * when the object cannot be compared with the elements in - * this TreeSet - * @exception NullPointerException - * when the object is null and the comparator cannot handle - * null + * the object to remove. + * @return {@code true} if this {@code TreeSet} was modified, {@code false} + * otherwise. + * @throws ClassCastException + * when the object cannot be compared with the elements in this + * {@code TreeSet}. + * @throws NullPointerException + * when the object is null and the comparator cannot handle + * null. */ @Override public boolean remove(Object object) { @@ -292,9 +285,9 @@ } /** - * Answers the number of elements in this TreeSet. + * Returns the number of elements in this {@code TreeSet}. * - * @return the number of elements in this TreeSet + * @return the number of elements in this {@code TreeSet}. */ @Override public int size() { @@ -302,24 +295,23 @@ } /** - * Answers a SortedSet of the specified portion of this TreeSet which - * contains elements greater or equal to the start element but less than the - * end element. The returned SortedSet is backed by this TreeSet so changes - * to one are reflected by the other. + * Returns a SortedSet of the specified portion of this {@code TreeSet} + * which contains elements greater or equal to the start element but less + * than the end element. The returned SortedSet is backed by this + * {@code TreeSet} so changes to one are reflected by the other. * * @param start - * the start element + * the start element. * @param end - * the end element - * @return a subset where the elements are greater or equal to - * start and less than end - * - * @exception ClassCastException - * when the start or end object cannot be compared with the - * elements in this TreeSet - * @exception NullPointerException - * when the start or end object is null and the comparator - * cannot handle null + * the end element (exclusive). + * @return a subset where the elements are greater or equal to {@code start} + * and less than {@code end} + * @throws ClassCastException + * when the start or end object cannot be compared with the + * elements in this {@code TreeSet}. + * @throws NullPointerException + * when the start or end object is null and the comparator + * cannot handle null. */ @SuppressWarnings("unchecked") public SortedSet subSet(E start, E end) { @@ -337,22 +329,20 @@ } /** - * Answers a SortedSet of the specified portion of this TreeSet which - * contains elements greater or equal to the start element. The returned - * SortedSet is backed by this TreeSet so changes to one are reflected by - * the other. + * Returns a SortedSet of the specified portion of this {@code TreeSet} + * which contains elements greater or equal to the start element. The + * returned SortedSet is backed by this {@code TreeSet} so changes to one + * are reflected by the other. * * @param start - * the start element - * @return a subset where the elements are greater or equal to - * start - * - * @exception ClassCastException - * when the start object cannot be compared with the elements - * in this TreeSet - * @exception NullPointerException - * when the start object is null and the comparator cannot - * handle null + * the start element. + * @return a subset where the elements are greater or equal to {@code start} + * @throws ClassCastException + * when the start object cannot be compared with the elements in + * this {@code TreeSet}. + * @throws NullPointerException + * when the start object is null and the comparator cannot + * handle null. */ @SuppressWarnings("unchecked") public SortedSet tailSet(E start) { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java Thu May 7 21:43:41 2009 @@ -27,20 +27,16 @@ import org.apache.harmony.luni.util.Msg; /** - *

* UUID is an immutable representation of a 128-bit universally unique * identifier (UUID). - *

*

* There are multiple, variant layouts of UUIDs, but this class is based upon * variant 2 of RFC 4122, the * Leach-Salz variant. This class can be used to model alternate variants, but * most of the methods will be unsupported in those cases; see each method for * details. - *

- * + * * @since 1.5 - * @author Nathan Beyer (Harmony) */ public final class UUID implements Serializable, Comparable { @@ -61,8 +57,7 @@ /** *

* Constructs an instance with the specified bits. - *

- * + * * @param mostSigBits * The 64 most significant bits of the UUID. * @param leastSigBits @@ -78,8 +73,7 @@ /** *

* Sets up the transient fields of this instance based on the current values - * of the mostSigBits and leastSigBits fields. - *

+ * of the {@code mostSigBits} and {@code leastSigBits} fields. */ private void init() { // setup hash field @@ -123,9 +117,8 @@ *

* Generates a variant 2, version 4 (randomly generated number) UUID as per * RFC 4122. - *

- * - * @return A UUID instance. + * + * @return an UUID instance. */ public static UUID randomUUID() { byte[] data; @@ -162,9 +155,10 @@ *

* Generates a variant 2, version 3 (name-based, MD5-hashed) UUID as per RFC 4122. - *

- * - * @return A UUID instance. + * + * @param name + * the name used as byte array to create an UUID. + * @return an UUID instance. */ public static UUID nameUUIDFromBytes(byte[] name) { if (name == null) { @@ -204,15 +198,14 @@ /** *

* Parses a UUID string with the format defined by {@link #toString()}. - *

- * + * * @param uuid - * The UUID string to parse. - * @return A UUID instance. + * the UUID string to parse. + * @return an UUID instance. * @throws NullPointerException - * if uuid is null. + * if {@code uuid} is {@code null}. * @throws IllegalArgumentException - * if uuid is not formatted correctly. + * if {@code uuid} is not formatted correctly. */ public static UUID fromString(String uuid) { if (uuid == null) { @@ -254,9 +247,8 @@ /** *

* The 64 least significant bits of the UUID. - *

- * - * @return A long value. + * + * @return the 64 least significant bits. */ public long getLeastSignificantBits() { return leastSigBits; @@ -265,9 +257,8 @@ /** *

* The 64 most significant bits of the UUID. - *

- * - * @return A long value. + * + * @return the 64 most significant bits. */ public long getMostSignificantBits() { return mostSigBits; @@ -278,7 +269,6 @@ * The version of the variant 2 UUID as per RFC 4122. If the variant * is not 2, then the version will be 0. - *

*
    *
  • 1 - Time-based UUID
    • *
  • 2 - DCE Security UUID
    • @@ -287,7 +277,7 @@ *
  • 5 - Name-based with SHA-1 hashing UUID
    • *
* - * @return An int value. + * @return an {@code int} value. */ public int version() { return version; @@ -297,7 +287,6 @@ *

* The variant of the UUID as per RFC 4122. - *

*
    *
  • 0 - Reserved for NCS compatibility
    • *
  • 2 - RFC 4122/Leach-Salz
    • @@ -305,7 +294,7 @@ *
  • 7 - Reserved for future use
    • *
* - * @return An int value. + * @return an {@code int} value. */ public int variant() { return variant; @@ -315,9 +304,8 @@ *

* The timestamp value of the version 1, variant 2 UUID as per RFC 4122. - *

- * - * @return A long value. + * + * @return a {@code long} value. * @throws UnsupportedOperationException * if {@link #version()} is not 1. */ @@ -332,9 +320,8 @@ *

* The clock sequence value of the version 1, variant 2 UUID as per RFC 4122. - *

- * - * @return A long value. + * + * @return a {@code long} value. * @throws UnsupportedOperationException * if {@link #version()} is not 1. */ @@ -349,9 +336,8 @@ *

* The node value of the version 1, variant 2 UUID as per RFC 4122. - *

- * - * @return A long value. + * + * @return a {@code long} value. * @throws UnsupportedOperationException * if {@link #version()} is not 1. */ @@ -367,12 +353,11 @@ * Compares this UUID to the specified UUID. The natural ordering of UUIDs * is based upon the value of the bits from most significant to least * significant. - *

- * + * * @param uuid - * The UUID to compare to. - * @return A value of -1, 0 or 1 if this UUID is less than, equal to or - * greater than uuid. + * the UUID to compare to. + * @return a value of -1, 0 or 1 if this UUID is less than, equal to or + * greater than {@code uuid}. */ public int compareTo(UUID uuid) { if (uuid == this) { @@ -396,15 +381,14 @@ /** *

- * Compares this UUID to another object for equality. If object - * is not null, a UUID instance and all bits are equals, - * then true is returned. - *

- * + * Compares this UUID to another object for equality. If {@code object} + * is not {@code null}, is a UUID instance, and all bits are equal, then + * {@code true} is returned. + * * @param object - * The Object to compare to. - * @return A true if this UUID is equal to - * object or false if not. + * the {@code Object} to compare to. + * @return {@code true} if this UUID is equal to {@code object} + * or {@code false} if not. */ @Override public boolean equals(Object object) { @@ -430,9 +414,8 @@ *

* Returns a hash value for this UUID that is consistent with the * {@link #equals(Object)} method. - *

- * - * @return An int value. + * + * @return an {@code int} value. */ @Override public int hashCode() { @@ -443,8 +426,7 @@ *

* Returns a string representation of this UUID in the following format, as * per RFC 4122. - *

- * + * * 
      *            UUID                   = time-low "-" time-mid "-"
      *                                     time-high-and-version "-"
@@ -463,7 +445,7 @@
      *                "A" / "B" / "C" / "D" / "E" / "F"
      *
* - * @return A String instance. + * @return a String instance. */ @Override public String toString() { @@ -494,14 +476,13 @@ /** *

* Resets the transient fields to match the behavior of the constructor. - *

* * @param in - * The InputStream to read from. + * the {@code InputStream} to read from. * @throws IOException - * if in throws it. + * if {@code in} throws it. * @throws ClassNotFoundException - * if in throws it. + * if {@code in} throws it. */ private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java Thu May 7 21:43:41 2009 @@ -18,21 +18,22 @@ import org.apache.harmony.luni.util.Msg; /** - * The unchecked exception will be thrown out if the format conversion is - * unknown. + * An {@code UnknownFormatConversionException} will be thrown if the format + * conversion is unknown. + * + * @see java.lang.RuntimeException */ public class UnknownFormatConversionException extends IllegalFormatException { - private static final long serialVersionUID = 19060418L; private String s; /** - * Constructs an UnknownFormatConversionException with the unknown format - * conversion. + * Constructs an {@code UnknownFormatConversionException} with the unknown + * format conversion. * - * @param s - * The unknown format conversion + * @param s + * the unknown format conversion. */ public UnknownFormatConversionException(String s) { this.s = s; @@ -41,7 +42,7 @@ /** * Returns the conversion associated with the exception. * - * @return The conversion associated with the exception. + * @return the conversion associated with the exception. */ public String getConversion() { return s; @@ -50,7 +51,7 @@ /** * Returns the message of the exception. * - * @return The message of the exception. + * @return the message of the exception. */ @Override public String getMessage() { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java Thu May 7 21:43:41 2009 @@ -19,7 +19,10 @@ import org.apache.harmony.luni.util.Msg; /** - * The unchecked exception will be thrown out if there is an unknown flag. + * An {@code UnknownFormatFlagsException} will be thrown if there is + * an unknown flag. + * + * @see java.lang.RuntimeException */ public class UnknownFormatFlagsException extends IllegalFormatException { @@ -28,10 +31,11 @@ private String flags; /** - * Constructs an UnknownFormatFlagsException with the specified flags. + * Constructs a new {@code UnknownFormatFlagsException} with the specified + * flags. * * @param f - * The specified flags. + * the specified flags. */ public UnknownFormatFlagsException(String f) { if (null == f) { @@ -43,7 +47,7 @@ /** * Returns the flags associated with the exception. * - * @return The flags associated with the exception. + * @return the flags associated with the exception. */ public String getFlags() { return flags; @@ -52,7 +56,7 @@ /** * Returns the message associated with the exception. * - * @return The message associated with the exception. + * @return the message associated with the exception. */ @Override public String getMessage() { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java Thu May 7 21:43:41 2009 @@ -23,18 +23,18 @@ import java.lang.reflect.Array; /** - * Vector is a variable size contiguous indexable array of Objects. The size of - * the Vector is the number of Objects it contains. The capacity of the Vector - * is the number of Objects it can hold. + * Vector is a variable size contiguous indexable array of objects. The size of + * the vector is the number of objects it contains. The capacity of the vector + * is the number of objects it can hold. *

- * Objects may be inserted at any position up to the size of the Vector, - * increasing the size of the Vector. Objects at any position in the Vector may - * be removed, shrinking the size of the Vector. Objects at any position in the - * Vector may be replaced, which does not affect the Vector size. + * Objects may be inserted at any position up to the size of the vector, thus + * increasing the size of the vector. Objects at any position in the vector may + * be removed, thus shrinking the size of the Vector. Objects at any position in + * the Vector may be replaced, which does not affect the vector's size. *

- * The capacity of a Vector may be specified when the Vector is created. If the - * capacity of the Vector is exceeded, the capacity is increased, doubling by - * default. + * The capacity of a vector may be specified when the vector is created. If the + * capacity of the vector is exceeded, the capacity is increased (doubled by + * default). * * @see java.lang.StringBuffer */ @@ -55,37 +55,42 @@ /** * How many elements should be added to the vector when it is detected that - * it needs to grow to accommodate extra entries. + * it needs to grow to accommodate extra entries. If this value is zero or + * negative the size will be doubled if an increase is needed. */ protected int capacityIncrement; private static final int DEFAULT_SIZE = 10; /** - * Constructs a new Vector using the default capacity. + * Constructs a new vector using the default capacity. */ public Vector() { this(DEFAULT_SIZE, 0); } /** - * Constructs a new Vector using the specified capacity. + * Constructs a new vector using the specified capacity. * * @param capacity - * the initial capacity of the new vector + * the initial capacity of the new vector. + * @throws IllegalArgumentException + * if {@code capacity} is negative. */ public Vector(int capacity) { this(capacity, 0); } /** - * Constructs a new Vector using the specified capacity and capacity + * Constructs a new vector using the specified capacity and capacity * increment. * * @param capacity - * the initial capacity of the new Vector + * the initial capacity of the new vector. * @param capacityIncrement - * the amount to increase the capacity when this Vector is full + * the amount to increase the capacity when this vector is full. + * @throws IllegalArgumentException + * if {@code capacity} is negative. */ public Vector(int capacity, int capacityIncrement) { if (capacity < 0) { @@ -97,13 +102,12 @@ } /** - * Constructs a new instance of Vector containing the - * elements in collection. The order of the elements in the - * new Vector is dependent on the iteration order of the seed - * collection. + * Constructs a new instance of {@code Vector} containing the elements in + * {@code collection}. The order of the elements in the new {@code Vector} + * is dependent on the iteration order of the seed collection. * * @param collection - * the collection of elements to add + * the collection of elements to add. */ public Vector(Collection collection) { this(collection.size(), 0); @@ -119,19 +123,17 @@ } /** - * Adds the specified object into this Vector at the specified location. The - * object is inserted before any previous element at the specified location. - * If the location is equal to the size of this Vector, the object is added - * at the end. + * Adds the specified object into this vector at the specified location. The + * object is inserted before any element with the same or a higher index + * increasing their index by 1. If the location is equal to the size of this + * vector, the object is added at the end. * * @param location - * the index at which to insert the element + * the index at which to insert the element. * @param object - * the object to insert in this Vector - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 || > size() - * + * the object to insert in this vector. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0 || location > size()}. * @see #addElement * @see #size */ @@ -141,11 +143,11 @@ } /** - * Adds the specified object at the end of this Vector. + * Adds the specified object at the end of this vector. * * @param object - * the object to add to the Vector - * @return true + * the object to add to the vector. + * @return {@code true} */ @Override public synchronized boolean add(E object) { @@ -158,19 +160,19 @@ } /** - * Inserts the objects in the specified Collection at the specified location - * in this Vector. The objects are inserted in the order in which they are - * returned from the Collection iterator. + * Inserts the objects in the specified collection at the specified location + * in this vector. The objects are inserted in the order in which they are + * returned from the Collection iterator. The elements with an index equal + * or higher than {@code location} have their index increased by the size of + * the added collection. * * @param location - * the location to insert the objects + * the location to insert the objects. * @param collection - * the Collection of objects - * @return true if this Vector is modified, false otherwise - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 or - * location > size() + * the collection of objects. + * @return {@code true} if this vector is modified, {@code false} otherwise. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0} or {@code location > size()}. */ @Override public synchronized boolean addAll(int location, @@ -201,11 +203,11 @@ } /** - * Adds the objects in the specified Collection to the end of this Vector. + * Adds the objects in the specified collection to the end of this vector. * * @param collection - * the Collection of objects - * @return true if this Vector is modified, false otherwise + * the collection of objects. + * @return {@code true} if this vector is modified, {@code false} otherwise. */ @Override public synchronized boolean addAll(Collection collection) { @@ -213,10 +215,10 @@ } /** - * Adds the specified object at the end of this Vector. + * Adds the specified object at the end of this vector. * * @param object - * the object to add to the Vector + * the object to add to the vector. */ public synchronized void addElement(E object) { if (elementCount == elementData.length) { @@ -227,10 +229,9 @@ } /** - * Answers the number of elements this Vector can hold without growing. - * - * @return the capacity of this Vector + * Returns the number of elements this vector can hold without growing. * + * @return the capacity of this vector. * @see #ensureCapacity * @see #size */ @@ -239,7 +240,7 @@ } /** - * Removes all elements from this Vector, leaving it empty. + * Removes all elements from this vector, leaving it empty. * * @see #isEmpty * @see #size @@ -250,11 +251,10 @@ } /** - * Answers a new Vector with the same elements, size, capacity and capacity - * increment as this Vector. - * - * @return a shallow copy of this Vector + * Returns a new vector with the same elements, size, capacity and capacity + * increment as this vector. * + * @return a shallow copy of this vector. * @see java.lang.Cloneable */ @Override @@ -270,12 +270,12 @@ } /** - * Searches this Vector for the specified object. + * Searches this vector for the specified object. * * @param object - * the object to look for in this Vector - * @return true if object is an element of this Vector, false otherwise - * + * the object to look for in this vector. + * @return {@code true} if object is an element of this vector, + * {@code false} otherwise. * @see #indexOf(Object) * @see #indexOf(Object, int) * @see java.lang.Object#equals @@ -286,12 +286,12 @@ } /** - * Searches this Vector for all objects in the specified Collection. + * Searches this vector for all objects in the specified collection. * * @param collection - * the Collection of objects - * @return true if all objects in the specified Collection are elements of - * this Vector, false otherwise + * the collection of objects. + * @return {@code true} if all objects in the specified collection are + * elements of this vector, {@code false} otherwise. */ @Override public synchronized boolean containsAll(Collection collection) { @@ -299,13 +299,14 @@ } /** - * Attempts to copy elements contained by this Vector into - * the corresponding elements of the supplied Object array. + * Attempts to copy elements contained by this {@code Vector} into the + * corresponding elements of the supplied {@code Object} array. * * @param elements - * the Object array into which the elements of - * this Vector are copied - * + * the {@code Object} array into which the elements of this + * vector are copied. + * @throws IndexOutOfBoundsException + * if {@code elements} is not big enough. * @see #clone */ public synchronized void copyInto(Object[] elements) { @@ -313,15 +314,13 @@ } /** - * Answers the element at the specified location in this Vector. + * Returns the element at the specified location in this vector. * * @param location - * the index of the element to return in this Vector - * @return the element at the specified location - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 || >= size() - * + * the index of the element to return in this vector. + * @return the element at the specified location. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0 || location >= size()}. * @see #size */ @SuppressWarnings("unchecked") @@ -333,11 +332,10 @@ } /** - * Answers an Enumeration on the elements of this Vector. The results of the - * Enumeration may be affected if the contents of this Vector are modified. - * - * @return an Enumeration of the elements of this Vector + * Returns an enumeration on the elements of this vector. The results of the + * enumeration may be affected if the contents of this vector is modified. * + * @return an enumeration of the elements of this vector. * @see #elementAt * @see Enumeration */ @@ -362,13 +360,12 @@ } /** - * Ensures that this Vector can hold the specified number of elements + * Ensures that this vector can hold the specified number of elements * without growing. * * @param minimumCapacity * the minimum number of elements that this vector will hold - * before growing - * + * before growing. * @see #capacity */ public synchronized void ensureCapacity(int minimumCapacity) { @@ -381,15 +378,14 @@ } /** - * Compares the specified object to this Vector and answer if they are + * Compares the specified object to this vector and returns if they are * equal. The object must be a List which contains the same objects in the * same order. * * @param object * the object to compare with this object - * @return true if the specified object is equal to this Vector, false - * otherwise - * + * @return {@code true} if the specified object is equal to this vector, + * {@code false} otherwise. * @see #hashCode */ @Override @@ -417,13 +413,11 @@ } /** - * Answers the first element in this Vector. - * - * @return the element at the first position - * - * @exception NoSuchElementException - * when this vector is empty + * Returns the first element in this vector. * + * @return the element at the first position. + * @throws NoSuchElementException + * if this vector is empty. * @see #elementAt * @see #lastElement * @see #size @@ -437,15 +431,13 @@ } /** - * Answers the element at the specified location in this Vector. + * Returns the element at the specified location in this vector. * * @param location - * the index of the element to return in this Vector - * @return the element at the specified location - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 || >= size() - * + * the index of the element to return in this vector. + * @return the element at the specified location. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0 || location >= size()}. * @see #size */ @Override @@ -500,11 +492,10 @@ } /** - * Answers an integer hash code for the receiver. Objects which are equal - * answer the same value for this method. - * - * @return the receiver's hash + * Returns an integer hash code for the receiver. Objects which are equal + * return the same value for this method. * + * @return the receiver's hash. * @see #equals */ @Override @@ -518,15 +509,14 @@ } /** - * Searches in this Vector for the index of the specified object. The search + * Searches in this vector for the index of the specified object. The search * for the object starts at the beginning and moves towards the end of this - * Vector. + * vector. * * @param object - * the object to find in this Vector - * @return the index in this Vector of the specified element, -1 if the - * element isn't found - * + * the object to find in this vector. + * @return the index in this vector of the specified element, -1 if the + * element isn't found. * @see #contains * @see #lastIndexOf(Object) * @see #lastIndexOf(Object, int) @@ -537,20 +527,18 @@ } /** - * Searches in this Vector for the index of the specified object. The search + * Searches in this vector for the index of the specified object. The search * for the object starts at the specified location and moves towards the end - * of this Vector. + * of this vector. * * @param object - * the object to find in this Vector + * the object to find in this vector. * @param location - * the index at which to start searching - * @return the index in this Vector of the specified element, -1 if the - * element isn't found - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 - * + * the index at which to start searching. + * @return the index in this vector of the specified element, -1 if the + * element isn't found. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0}. * @see #contains * @see #lastIndexOf(Object) * @see #lastIndexOf(Object, int) @@ -573,19 +561,18 @@ } /** - * Inserts the specified object into this Vector at the specified location. + * Inserts the specified object into this vector at the specified location. * This object is inserted before any previous element at the specified - * location. If the location is equal to the size of this Vector, the object - * is added at the end. + * location. All elements with an index equal or greater than + * {@code location} have their index increased by 1. If the location is + * equal to the size of this vector, the object is added at the end. * * @param object - * the object to insert in this Vector + * the object to insert in this vector. * @param location - * the index at which to insert the element - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 || > size() - * + * the index at which to insert the element. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0 || location > size()}. * @see #addElement * @see #size */ @@ -608,10 +595,10 @@ } /** - * Answers if this Vector has no elements, a size of zero. - * - * @return true if this Vector has no elements, false otherwise + * Returns if this vector has no elements, a size of zero. * + * @return {@code true} if this vector has no elements, {@code false} + * otherwise. * @see #size */ @Override @@ -620,13 +607,11 @@ } /** - * Answers the last element in this Vector. - * - * @return the element at the last position - * - * @exception NoSuchElementException - * when this vector is empty + * Returns the last element in this vector. * + * @return the element at the last position. + * @throws NoSuchElementException + * if this vector is empty. * @see #elementAt * @see #firstElement * @see #size @@ -641,15 +626,14 @@ } /** - * Searches in this Vector for the index of the specified object. The search + * Searches in this vector for the index of the specified object. The search * for the object starts at the end and moves towards the start of this - * Vector. + * vector. * * @param object - * the object to find in this Vector - * @return the index in this Vector of the specified element, -1 if the - * element isn't found - * + * the object to find in this vector. + * @return the index in this vector of the specified element, -1 if the + * element isn't found. * @see #contains * @see #indexOf(Object) * @see #indexOf(Object, int) @@ -660,20 +644,18 @@ } /** - * Searches in this Vector for the index of the specified object. The search + * Searches in this vector for the index of the specified object. The search * for the object starts at the specified location and moves towards the - * start of this Vector. + * start of this vector. * * @param object - * the object to find in this Vector + * the object to find in this vector. * @param location - * the index at which to start searching - * @return the index in this Vector of the specified element, -1 if the - * element isn't found - * - * @exception ArrayIndexOutOfBoundsException - * when location >= size() - * + * the index at which to start searching. + * @return the index in this vector of the specified element, -1 if the + * element isn't found. + * @throws ArrayIndexOutOfBoundsException + * if {@code location >= size()}. * @see #contains * @see #indexOf(Object) * @see #indexOf(Object, int) @@ -698,10 +680,16 @@ throw new ArrayIndexOutOfBoundsException(location); } - /* - * (non-Javadoc) + /** + * Removes the object at the specified location from this vector. All + * elements with an index bigger than {@code location} have their index + * decreased by 1. * - * @see java.util.List#remove(int) + * @param location + * the index of the object to remove. + * @return the removed object. + * @throws IndexOutOfBoundsException + * if {@code location < 0 || location >= size()}. */ @SuppressWarnings("unchecked") @Override @@ -723,12 +711,14 @@ /** * Removes the first occurrence, starting at the beginning and moving - * towards the end, of the specified object from this Vector. + * towards the end, of the specified object from this vector. All elements + * with an index bigger than the element that gets removed have their index + * decreased by 1. * * @param object - * the object to remove from this Vector - * @return true if the specified object was found, false otherwise - * + * the object to remove from this vector. + * @return {@code true} if the specified object was found, {@code false} + * otherwise. * @see #removeAllElements * @see #removeElementAt * @see #size @@ -739,12 +729,14 @@ } /** - * Removes all occurrences in this Vector of each object in the specified + * Removes all occurrences in this vector of each object in the specified * Collection. * * @param collection - * the Collection of objects to remove - * @return true if this Vector is modified, false otherwise + * the collection of objects to remove. + * @return {@code true} if this vector is modified, {@code false} otherwise. + * @see #remove(Object) + * @see #contains(Object) */ @Override public synchronized boolean removeAll(Collection collection) { @@ -752,7 +744,7 @@ } /** - * Removes all elements from this Vector, leaving the size zero and the + * Removes all elements from this vector, leaving the size zero and the * capacity unchanged. * * @see #isEmpty @@ -768,12 +760,14 @@ /** * Removes the first occurrence, starting at the beginning and moving - * towards the end, of the specified object from this Vector. + * towards the end, of the specified object from this vector. All elements + * with an index bigger than the element that gets removed have their index + * decreased by 1. * * @param object - * the object to remove from this Vector - * @return true if the specified object was found, false otherwise - * + * the object to remove from this vector. + * @return {@code true} if the specified object was found, {@code false} + * otherwise. * @see #removeAllElements * @see #removeElementAt * @see #size @@ -788,15 +782,14 @@ } /** - * Removes the element found at index position location from - * this Vector and decrements the size accordingly. + * Removes the element found at index position {@code location} from + * this {@code Vector}. All elements with an index bigger than + * {@code location} have their index decreased by 1. * * @param location - * the index of the element to remove - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 || >= size() - * + * the index of the element to remove. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0 || location >= size()}. * @see #removeElement * @see #removeAllElements * @see #size @@ -818,16 +811,16 @@ /** * Removes the objects in the specified range from the start to the, but not - * including, end index. + * including, end index. All elements with an index bigger than or equal to + * {@code end} have their index decreased by {@code end - start}. * * @param start - * the index at which to start removing + * the index at which to start removing. * @param end - * the index one past the end of the range to remove - * - * @exception IndexOutOfBoundsException - * when start < 0, start > end or - * end > size() + * the index one past the end of the range to remove. + * @throws IndexOutOfBoundsException + * if {@code start < 0, start > end} or + * {@code end > size()}. */ @Override protected void removeRange(int start, int end) { @@ -852,12 +845,13 @@ } /** - * Removes all objects from this Vector that are not contained in the - * specified Collection. + * Removes all objects from this vector that are not contained in the + * specified collection. * * @param collection - * the Collection of objects to retain - * @return true if this Vector is modified, false otherwise + * the collection of objects to retain. + * @return {@code true} if this vector is modified, {@code false} otherwise. + * @see #remove(Object) */ @Override public synchronized boolean retainAll(Collection collection) { @@ -865,18 +859,16 @@ } /** - * Replaces the element at the specified location in this Vector with the + * Replaces the element at the specified location in this vector with the * specified object. * * @param location - * the index at which to put the specified object + * the index at which to put the specified object. * @param object - * the object to add to this Vector - * @return the previous element at the location - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 || >= size() - * + * the object to add to this vector. + * @return the previous element at the location. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0 || location >= size()}. * @see #size */ @SuppressWarnings("unchecked") @@ -891,17 +883,15 @@ } /** - * Replaces the element at the specified location in this Vector with the + * Replaces the element at the specified location in this vector with the * specified object. * * @param object - * the object to add to this Vector + * the object to add to this vector. * @param location - * the index at which to put the specified object - * - * @exception ArrayIndexOutOfBoundsException - * when location < 0 || >= size() - * + * the index at which to put the specified object. + * @throws ArrayIndexOutOfBoundsException + * if {@code location < 0 || location >= size()}. * @see #size */ public synchronized void setElementAt(E object, int location) { @@ -913,14 +903,13 @@ } /** - * Sets the size of this Vector to the specified size. If there are more - * than length elements in this Vector, the elements at end are lost. If - * there are less than length elements in the Vector, the additional + * Sets the size of this vector to the specified size. If there are more + * than length elements in this vector, the elements at end are lost. If + * there are less than length elements in the vector, the additional * elements contain null. * * @param length - * the new size of this Vector - * + * the new size of this vector. * @see #size */ public synchronized void setSize(int length) { @@ -936,10 +925,9 @@ } /** - * Answers the number of elements in this Vector. - * - * @return the number of elements in this Vector + * Returns the number of elements in this vector. * + * @return the number of elements in this vector. * @see #elementCount * @see #lastElement */ @@ -949,19 +937,19 @@ } /** - * Answers a List of the specified portion of this Vector from the start + * Returns a List of the specified portion of this vector from the start * index to one less than the end index. The returned List is backed by this - * Vector so changes to one are reflected by the other. + * vector so changes to one are reflected by the other. * * @param start - * the index at which to start the sublist + * the index at which to start the sublist. * @param end - * the index one past the end of the sublist - * @return a List of a portion of this Vector - * - * @exception IndexOutOfBoundsException - * when start < 0 or end > size() - * @exception IllegalArgumentException when start > end + * the index one past the end of the sublist. + * @return a List of a portion of this vector. + * @throws IndexOutOfBoundsException + * if {@code start < 0} or {@code end > size()}. + * @throws IllegalArgumentException + * if {@code start > end}. */ @Override public synchronized List subList(int start, int end) { @@ -970,9 +958,9 @@ } /** - * Answers a new array containing all elements contained in this Vector. + * Returns a new array containing all elements contained in this vector. * - * @return an array of the elements from this Vector + * @return an array of the elements from this vector. */ @Override public synchronized Object[] toArray() { @@ -982,19 +970,18 @@ } /** - * Answers an array containing all elements contained in this Vector. If the + * Returns an array containing all elements contained in this vector. If the * specified array is large enough to hold the elements, the specified array * is used, otherwise an array of the same type is created. If the specified - * array is used and is larger than this Vector, the array element following + * array is used and is larger than this vector, the array element following * the collection elements is set to null. * * @param contents - * the array - * @return an array of the elements from this Vector - * - * @exception ArrayStoreException - * when the type of an element in this Vector cannot be - * stored in the type of the specified array + * the array to fill. + * @return an array of the elements from this vector. + * @throws ArrayStoreException + * if the type of an element in this vector cannot be + * stored in the type of the specified array. */ @Override @SuppressWarnings("unchecked") @@ -1011,10 +998,9 @@ } /** - * Answers the string representation of this Vector. - * - * @return the string representation of this Vector + * Returns the string representation of this vector. * + * @return the string representation of this vector. * @see #elements */ @Override @@ -1043,7 +1029,7 @@ } /** - * Sets the capacity of this Vector to be the same as the size. + * Sets the capacity of this vector to be the same as the size. * * @see #capacity * @see #ensureCapacity