Javadoc changes for v3.2

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@405927 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/ExtendedProperties.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2001-2005 The Apache Software Foundation
+ *  Copyright 2001-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -69,7 +69,7 @@ import java.util.Vector;
  *  </li>
  *  <li>
  *   If a <i>key</i> is used more than once, the values are appended
- *   like if they were on the same line separated with commas.
+ *   as if they were on the same line separated with commas.
  *  </li>
  *  <li>
  *   Blank lines and lines starting with character '#' are skipped.

src/java/org/apache/commons/collections/buffer/BoundedBuffer.java

@@ -33,8 +33,11 @@ import org.apache.commons.collections.iterators.AbstractIteratorDecorator;
  * behaviour to another buffer. If you just want a bounded buffer then
  * you should use {@link BoundedFifoBuffer} or {@link CircularFifoBuffer}.
  * <p>
- * The decoration methods allow you to specify a timeout value, which
+ * The decoration methods allow you to specify a timeout value.
- * causes the add methods to wait for up to the specified wait period.
+ * This alters the behaviour of the add methods when the buffer is full.
+ * Normally, when the buffer is full, the add method will throw an exception.
+ * With a timeout, the add methods will wait for up to the timeout period
+ * to try and add the elements.
  *
  * @author James Carman
  * @author Stephen Colebourne

src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2002-2004 The Apache Software Foundation
+ *  Copyright 2002-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -32,7 +32,7 @@ import org.apache.commons.collections.BufferUnderflowException;
 
 /**
  * The BoundedFifoBuffer is a very efficient implementation of
- * Buffer that does not alter the size of the buffer at runtime.
+ * <code>Buffer</code> that is of a fixed size.
  * <p>
  * The removal order of a <code>BoundedFifoBuffer</code> is based on the 
  * insertion order; elements are removed in the same order in which they

src/java/org/apache/commons/collections/buffer/PriorityBuffer.java

@@ -45,10 +45,11 @@ import org.apache.commons.collections.BufferUnderflowException;
  * {@link org.apache.commons.collections.BufferUtils#synchronizedBuffer(Buffer)} or
  * {@link org.apache.commons.collections.buffer.SynchronizedBuffer#decorate(Buffer)}
  * to provide synchronized access to a <code>PriorityBuffer</code>:
- *
  * <pre>
  * Buffer heap = SynchronizedBuffer.decorate(new PriorityBuffer());
  * </pre>
+ * <p>
+ * This class is Serializable from Commons Collections 3.2.
  *
  * @since Commons Collections 3.0 (previously BinaryHeap v1.0)
  * @version $Revision$ $Date$

src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2002-2004 The Apache Software Foundation
+ *  Copyright 2002-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -27,7 +27,8 @@ import org.apache.commons.collections.Buffer;
 import org.apache.commons.collections.BufferUnderflowException;
 
 /**
- * UnboundedFifoBuffer is a very efficient buffer implementation.
+ * UnboundedFifoBuffer is a very efficient implementation of
+ * <code>Buffer</code> that can grow to any size.
  * According to performance testing, it exhibits a constant access time, but it
  * also outperforms ArrayList when used for the same purpose.
  * <p>

src/java/org/apache/commons/collections/functors/AllPredicate.java

@@ -41,7 +41,10 @@ public final class AllPredicate implements Predicate, PredicateDecorator, Serial
     
     /**
      * Factory to create the predicate.
-     * 
+     * <p>
+     * If the array is size zero, the predicate always returns true.
+     * If the array is size one, then that predicate is returned.
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>all</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
@@ -61,7 +64,10 @@ public final class AllPredicate implements Predicate, PredicateDecorator, Serial
 
     /**
      * Factory to create the predicate.
-     * 
+     * <p>
+     * If the collection is size zero, the predicate always returns true.
+     * If the collection is size one, then that predicate is returned.
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>all</code> predicate
      * @throws IllegalArgumentException if the predicates array is null

src/java/org/apache/commons/collections/functors/AnyPredicate.java

@@ -41,7 +41,10 @@ public final class AnyPredicate implements Predicate, PredicateDecorator, Serial
     
     /**
      * Factory to create the predicate.
-     * 
+     * <p>
+     * If the array is size zero, the predicate always returns false.
+     * If the array is size one, then that predicate is returned.
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>any</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
@@ -60,7 +63,10 @@ public final class AnyPredicate implements Predicate, PredicateDecorator, Serial
 
     /**
      * Factory to create the predicate.
-     * 
+     * <p>
+     * If the collection is size zero, the predicate always returns false.
+     * If the collection is size one, then that predicate is returned.
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>all</code> predicate
      * @throws IllegalArgumentException if the predicates array is null

src/java/org/apache/commons/collections/functors/NonePredicate.java

@@ -41,7 +41,9 @@ public final class NonePredicate implements Predicate, PredicateDecorator, Seria
     
     /**
      * Factory to create the predicate.
-     * 
+     * <p>
+     * If the array is size zero, the predicate always returns true.
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>any</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
@@ -58,7 +60,9 @@ public final class NonePredicate implements Predicate, PredicateDecorator, Seria
 
     /**
      * Factory to create the predicate.
-     * 
+     * <p>
+     * If the collection is size zero, the predicate always returns true.
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>one</code> predicate
      * @throws IllegalArgumentException if the predicates array is null

src/java/org/apache/commons/collections/functors/OnePredicate.java

@@ -41,7 +41,10 @@ public final class OnePredicate implements Predicate, PredicateDecorator, Serial
     
     /**
      * Factory to create the predicate.
-     * 
+     * <p>
+     * If the array is size zero, the predicate always returns false.
+     * If the array is size one, then that predicate is returned.
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>any</code> predicate
      * @throws IllegalArgumentException if the predicates array is null
@@ -61,7 +64,7 @@ public final class OnePredicate implements Predicate, PredicateDecorator, Serial
 
     /**
      * Factory to create the predicate.
-     * 
+     *
      * @param predicates  the predicates to check, cloned, not null
      * @return the <code>one</code> predicate
      * @throws IllegalArgumentException if the predicates array is null

src/java/org/apache/commons/collections/functors/StringValueTransformer.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2001-2004 The Apache Software Foundation
+ *  Copyright 2001-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -20,8 +20,9 @@ import java.io.Serializable;
 import org.apache.commons.collections.Transformer;
 
 /**
- * Transformer implementation that returns the <code>String.valueOf</code>.
+ * Transformer implementation that returns the result of calling
- * 
+ * <code>String.valueOf</code> on the input object.
+ *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  *

src/java/org/apache/commons/collections/keyvalue/AbstractKeyValue.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2003-2004 The Apache Software Foundation
+ *  Copyright 2003-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -18,7 +18,8 @@ package org.apache.commons.collections.keyvalue;
 import org.apache.commons.collections.KeyValue;
 
 /**
- * Abstract pair class to assist with creating KeyValue and MapEntry implementations.
+ * Abstract pair class to assist with creating <code>KeyValue</code>
+ * and {@link java.util.Map.Entry Map.Entry} implementations.
  *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
@@ -29,12 +30,12 @@ import org.apache.commons.collections.KeyValue;
  * @author Stephen Colebourne
  */
 public abstract class AbstractKeyValue implements KeyValue {
-    
+
     /** The key */
     protected Object key;
     /** The value */
     protected Object value;
-    
+
     /**
      * Constructs a new pair with the specified key and given value.
      *

src/java/org/apache/commons/collections/keyvalue/AbstractMapEntry.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2003-2004 The Apache Software Foundation
+ *  Copyright 2003-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -18,7 +18,8 @@ package org.apache.commons.collections.keyvalue;
 import java.util.Map;
 
 /**
- * Abstract Pair class to assist with creating correct Map Entry implementations.
+ * Abstract Pair class to assist with creating correct
+ * {@link java.util.Map.Entry Map.Entry} implementations.
  *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
@@ -29,7 +30,7 @@ import java.util.Map;
  * @author Stephen Colebourne
  */
 public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.Entry {
-    
+
     /**
      * Constructs a new entry with the given key and given value.
      *
@@ -43,9 +44,10 @@ public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.E
     // Map.Entry interface
     //-------------------------------------------------------------------------
     /** 
-     * Sets the value stored in this Map Entry.
+     * Sets the value stored in this <code>Map.Entry</code>.
      * <p>
-     * This Map Entry is not connected to a Map, so only the local data is changed.
+     * This <code>Map.Entry</code> is not connected to a Map, so only the
+     * local data is changed.
      *
      * @param value  the new value
      * @return the previous value
@@ -57,7 +59,7 @@ public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.E
     }
 
     /**
-     * Compares this Map Entry with another Map Entry.
+     * Compares this <code>Map.Entry</code> with another <code>Map.Entry</code>.
      * <p>
      * Implemented per API documentation of {@link java.util.Map.Entry#equals(Object)}
      * 
@@ -76,7 +78,7 @@ public abstract class AbstractMapEntry extends AbstractKeyValue implements Map.E
             (getKey() == null ? other.getKey() == null : getKey().equals(other.getKey())) &&
             (getValue() == null ? other.getValue() == null : getValue().equals(other.getValue()));
     }
-     
+
     /**
      * Gets a hashCode compatible with the equals method.
      * <p>

src/java/org/apache/commons/collections/keyvalue/AbstractMapEntryDecorator.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2003-2004 The Apache Software Foundation
+ *  Copyright 2003-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -20,8 +20,8 @@ import java.util.Map;
 import org.apache.commons.collections.KeyValue;
 
 /**
- * Provides a base decorator that allows additional functionality to be added
+ * Provides a base decorator that allows additional functionality to be
- * to a Map Entry.
+ * added to a {@link java.util.Map.Entry Map.Entry}.
  *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$

src/java/org/apache/commons/collections/keyvalue/DefaultKeyValue.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2003-2004 The Apache Software Foundation
+ *  Copyright 2003-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -20,7 +20,8 @@ import java.util.Map;
 import org.apache.commons.collections.KeyValue;
 
 /**
- * A mutable KeyValue pair that does not implement MapEntry.
+ * A mutable <code>KeyValue</code> pair that does not implement
+ * {@link java.util.Map.Entry Map.Entry}.
  * <p>
  * Note that a <code>DefaultKeyValue</code> instance may not contain
  * itself as a key or value.
@@ -53,7 +54,7 @@ public class DefaultKeyValue extends AbstractKeyValue {
     }
 
     /**
-     * Constructs a new pair from the specified KeyValue.
+     * Constructs a new pair from the specified <code>KeyValue</code>.
      *
      * @param pair  the pair to copy, must not be null
      * @throws NullPointerException if the entry is null
@@ -63,7 +64,7 @@ public class DefaultKeyValue extends AbstractKeyValue {
     }
 
     /**
-     * Constructs a new pair from the specified MapEntry.
+     * Constructs a new pair from the specified <code>Map.Entry</code>.
      *
      * @param entry  the entry to copy, must not be null
      * @throws NullPointerException if the entry is null
@@ -119,7 +120,7 @@ public class DefaultKeyValue extends AbstractKeyValue {
 
     //-----------------------------------------------------------------------
     /**
-     * Compares this Map Entry with another Map Entry.
+     * Compares this <code>Map.Entry</code> with another <code>Map.Entry</code>.
      * <p>
      * Returns true if the compared object is also a <code>DefaultKeyValue</code>,
      * and its key and value are equal to this object's key and value.

src/java/org/apache/commons/collections/keyvalue/DefaultMapEntry.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2001-2004 The Apache Software Foundation
+ *  Copyright 2001-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@ import org.apache.commons.collections.KeyValue;
 
 /**
  * A restricted implementation of {@link java.util.Map.Entry} that prevents
- * the MapEntry contract from being broken.
+ * the <code>Map.Entry</code> contract from being broken.
  *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
@@ -32,7 +32,7 @@ import org.apache.commons.collections.KeyValue;
  * @author Stephen Colebourne
  */
 public final class DefaultMapEntry extends AbstractMapEntry {
-    
+
     /**
      * Constructs a new entry with the specified key and given value.
      *
@@ -44,7 +44,7 @@ public final class DefaultMapEntry extends AbstractMapEntry {
     }
 
     /**
-     * Constructs a new entry from the specified KeyValue.
+     * Constructs a new entry from the specified <code>KeyValue</code>.
      *
      * @param pair  the pair to copy, must not be null
      * @throws NullPointerException if the entry is null
@@ -54,7 +54,7 @@ public final class DefaultMapEntry extends AbstractMapEntry {
     }
 
     /**
-     * Constructs a new entry from the specified MapEntry.
+     * Constructs a new entry from the specified <code>Map.Entry</code>.
      *
      * @param entry  the entry to copy, must not be null
      * @throws NullPointerException if the entry is null

src/java/org/apache/commons/collections/keyvalue/TiedMapEntry.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2003-2004 The Apache Software Foundation
+ *  Copyright 2003-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@ import java.util.Map;
 import org.apache.commons.collections.KeyValue;
 
 /**
- * A Map Entry tied to a map underneath.
+ * A {@link java.util.Map.Entry Map.Entry} tied to a map underneath.
  * <p>
  * This can be used to enable a map entry to make changes on the underlying
  * map, however this will probably mess up any iterators.
@@ -40,7 +40,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable {
     private final Map map;
     /** The key */
     private final Object key;
-    
+
     /**
      * Constructs a new entry with the given Map and key.
      *
@@ -88,7 +88,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable {
     }
 
     /**
-     * Compares this Map Entry with another Map Entry.
+     * Compares this <code>Map.Entry</code> with another <code>Map.Entry</code>.
      * <p>
      * Implemented per API documentation of {@link java.util.Map.Entry#equals(Object)}
      * 
@@ -108,7 +108,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable {
             (key == null ? other.getKey() == null : key.equals(other.getKey())) &&
             (value == null ? other.getValue() == null : value.equals(other.getValue()));
     }
-     
+
     /**
      * Gets a hashCode compatible with the equals method.
      * <p>
@@ -121,7 +121,7 @@ public class TiedMapEntry implements Map.Entry, KeyValue, Serializable {
         return (getKey() == null ? 0 : getKey().hashCode()) ^
                (value == null ? 0 : value.hashCode()); 
     }
-    
+
     /**
      * Gets a string version of the entry.
      * 

src/java/org/apache/commons/collections/keyvalue/UnmodifiableMapEntry.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2003-2004 The Apache Software Foundation
+ *  Copyright 2003-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,8 +21,8 @@ import org.apache.commons.collections.KeyValue;
 import org.apache.commons.collections.Unmodifiable;
 
 /**
- * A {@link java.util.Map.Entry} that throws UnsupportedOperationException
+ * A {@link java.util.Map.Entry Map.Entry} that throws
- * when <code>setValue</code> is called.
+ * UnsupportedOperationException when <code>setValue</code> is called.
  *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
@@ -30,7 +30,7 @@ import org.apache.commons.collections.Unmodifiable;
  * @author Stephen Colebourne
  */
 public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmodifiable {
-    
+
     /**
      * Constructs a new entry with the specified key and given value.
      *
@@ -42,7 +42,7 @@ public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmo
     }
 
     /**
-     * Constructs a new entry from the specified KeyValue.
+     * Constructs a new entry from the specified <code>KeyValue</code>.
      *
      * @param pair  the pair to copy, must not be null
      * @throws NullPointerException if the entry is null
@@ -52,7 +52,7 @@ public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmo
     }
 
     /**
-     * Constructs a new entry from the specified MapEntry.
+     * Constructs a new entry from the specified <code>Map.Entry</code>.
      *
      * @param entry  the entry to copy, must not be null
      * @throws NullPointerException if the entry is null
@@ -60,7 +60,7 @@ public final class UnmodifiableMapEntry extends AbstractMapEntry implements Unmo
     public UnmodifiableMapEntry(final Map.Entry entry) {
         super(entry.getKey(), entry.getValue());
     }
-    
+
     /**
      * Throws UnsupportedOperationException.
      * 

src/java/org/apache/commons/collections/list/GrowthList.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2005 The Apache Software Foundation
+ *  Copyright 2005-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * Decorates another <code>List</code> to make it seemlessly grow when
+ * Decorates another <code>List</code> to make it seamlessly grow when
  * indices larger than the list size are used on add and set,
  * avoiding most IndexOutOfBoundsExceptions.
  * <p>
@@ -34,7 +34,7 @@ import java.util.List;
  * not to use excessively large indices, as the internal list will grow to
  * match.
  * <p>
- * Trying to use any method other than add or set with an invalid inde will
+ * Trying to use any method other than add or set with an invalid index will
  * call the underlying list and probably result in an IndexOutOfBoundsException.
  * <p>
  * Take care when using this list with <code>null</code> values, as
@@ -45,12 +45,12 @@ import java.util.List;
  * <p>
  * This class differs from {@link LazyList} because here growth occurs on
  * set and add, where <code>LazyList</code> grows on get. However, they
- * could easily be used together by decorating twice.
+ * can be used together by decorating twice.
  *
  * @see LazyList
  * @since Commons Collections 3.2
  * @version $Revision: 155406 $ $Date$
- * 
+ *
  * @author Stephen Colebourne
  * @author Paul Legato
  */

src/java/org/apache/commons/collections/list/package.html

@@ -1,6 +1,6 @@
 <!-- $Id$ -->
  <!--
-   Copyright 2003-2004 The Apache Software Foundation
+   Copyright 2006 The Apache Software Foundation
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -23,7 +23,7 @@ This package contains implementations of the
 The following implementations are provided in the package:
 <ul>
 <li>TreeList - a list that is optimised for insertions and removals at any index in the list</li>
-<li>CursorableLinkedList - a list that can be modified while it's listIterator (cursor) is being used</li>
+<li>CursorableLinkedList - a list that can be modified while the listIterator (cursor) is being used</li>
 <li>NodeCachingLinkedList - a linked list that caches the storage nodes for a performance gain</li>
 </ul>
 </p>