From f98ef6d3ba19643262f5538bc5fc93249a75cd50 Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Tue, 12 Sep 2017 22:35:18 +1200 Subject: [PATCH] COLLECTIONS-653 fix Javadoc syntax for Java 8 --- .../commons/collections4/CollectionUtils.java | 6 ++--- .../commons/collections4/FactoryUtils.java | 9 ++++--- .../commons/collections4/FluentIterable.java | 8 +++--- .../org/apache/commons/collections4/Get.java | 17 ++++++++++++ .../commons/collections4/IterableGet.java | 4 +-- .../commons/collections4/IterableMap.java | 4 +-- .../apache/commons/collections4/MapUtils.java | 4 +-- .../org/apache/commons/collections4/Put.java | 8 ++++++ .../apache/commons/collections4/SetUtils.java | 4 +-- .../commons/collections4/SortedBidiMap.java | 2 +- .../collections4/TransformerUtils.java | 18 +++++++------ .../collections4/bag/CollectionBag.java | 6 ++--- .../collections4/bag/CollectionSortedBag.java | 6 ++--- .../commons/collections4/bag/HashBag.java | 7 +++++ .../commons/collections4/bag/TreeBag.java | 7 +++++ .../collections4/bag/UnmodifiableBag.java | 6 ++--- .../bag/UnmodifiableSortedBag.java | 6 ++--- .../collections4/bidimap/TreeBidiMap.java | 7 +++++ .../collection/CompositeCollection.java | 2 +- .../comparators/BooleanComparator.java | 9 ++++--- .../functors/CatchAndRethrowClosure.java | 2 +- .../functors/ComparatorPredicate.java | 26 +++++++++---------- .../functors/ConstantTransformer.java | 2 +- .../functors/InstantiateTransformer.java | 2 +- .../functors/PrototypeFactory.java | 10 ++++--- .../iterators/ArrayListIterator.java | 6 ++--- .../collections4/iterators/EmptyIterator.java | 4 +-- .../iterators/EmptyListIterator.java | 4 +-- .../iterators/EmptyMapIterator.java | 2 +- .../iterators/EmptyOrderedIterator.java | 2 +- .../iterators/EmptyOrderedMapIterator.java | 2 +- .../iterators/FilterListIterator.java | 11 ++++++-- .../iterators/IteratorIterable.java | 25 ++++++++++-------- .../iterators/ObjectArrayListIterator.java | 6 ++--- .../iterators/SingletonIterator.java | 2 +- .../iterators/SingletonListIterator.java | 2 +- .../AbstractSerializableListDecorator.java | 6 ++--- .../list/CursorableLinkedList.java | 7 +++++ .../list/NodeCachingLinkedList.java | 7 +++++ .../map/AbstractInputCheckedMapDecorator.java | 6 +++++ .../collections4/map/AbstractLinkedMap.java | 2 +- .../collections4/map/CaseInsensitiveMap.java | 11 +++++++- .../collections4/map/DefaultedMap.java | 6 ++--- .../map/EntrySetToMapIteratorAdapter.java | 2 +- .../collections4/map/FixedSizeMap.java | 6 ++--- .../collections4/map/FixedSizeSortedMap.java | 7 +++++ .../commons/collections4/map/Flat3Map.java | 7 +++++ .../commons/collections4/map/HashedMap.java | 7 +++++ .../commons/collections4/map/LRUMap.java | 11 ++++++-- .../commons/collections4/map/LazyMap.java | 6 ++--- .../commons/collections4/map/LinkedMap.java | 7 +++++ .../collections4/map/ListOrderedMap.java | 6 ++--- .../commons/collections4/map/MultiKeyMap.java | 6 ++--- .../collections4/map/MultiValueMap.java | 6 ++--- .../collections4/map/PassiveExpiringMap.java | 6 ++--- .../collections4/map/PredicatedMap.java | 6 ++--- .../map/ReferenceIdentityMap.java | 16 +++++++++++- .../collections4/map/ReferenceMap.java | 7 +++++ .../collections4/map/TransformedMap.java | 6 ++--- .../collections4/map/UnmodifiableMap.java | 6 ++--- .../map/UnmodifiableOrderedMap.java | 6 ++--- .../map/UnmodifiableSortedMap.java | 6 ++--- .../collections4/multiset/HashMultiSet.java | 7 +++++ .../multiset/UnmodifiableMultiSet.java | 6 ++--- .../collections4/multiset/package-info.java | 4 +-- .../properties/SortedProperties.java | 2 +- .../collections4/sequence/CommandVisitor.java | 2 +- .../set/AbstractSerializableSetDecorator.java | 6 ++--- .../set/UnmodifiableNavigableSet.java | 6 ++--- .../set/UnmodifiableSortedSet.java | 6 ++--- .../AbstractIterableGetMapDecorator.java | 6 ++--- .../splitmap/TransformedSplitMap.java | 6 ++--- .../trie/AbstractPatriciaTrie.java | 18 ++++++------- .../collections4/trie/PatriciaTrie.java | 21 ++++++++------- 74 files changed, 335 insertions(+), 178 deletions(-) diff --git a/src/main/java/org/apache/commons/collections4/CollectionUtils.java b/src/main/java/org/apache/commons/collections4/CollectionUtils.java index fb99785a8..e362db930 100644 --- a/src/main/java/org/apache/commons/collections4/CollectionUtils.java +++ b/src/main/java/org/apache/commons/collections4/CollectionUtils.java @@ -432,7 +432,7 @@ public class CollectionUtils { * Only those elements present in the collection will appear as * keys in the map. * - * @param the type of object in the returned {@link Map}. This is a super type of . + * @param the type of object in the returned {@link Map}. This is a super type of <I>. * @param coll the collection to get the cardinality map for, must not be null * @return the populated cardinality map */ @@ -483,7 +483,7 @@ public class CollectionUtils { *
    *
  • a.size() and b.size() represent the * total cardinality of a and b, resp.
    • - *
  • a.size() < Integer.MAXVALUE
    • + *
  • a.size() < Integer.MAXVALUE
    • *
* * @param a the first (sub?) collection, must not be null @@ -833,7 +833,7 @@ public class CollectionUtils { * Answers true if a predicate is true for every element of a * collection. *

- * A null predicate returns false.
+ * A null predicate returns false.
* A null or empty collection returns true. * * @param the type of object the {@link Iterable} contains diff --git a/src/main/java/org/apache/commons/collections4/FactoryUtils.java b/src/main/java/org/apache/commons/collections4/FactoryUtils.java index a32d831df..e65c0ba44 100644 --- a/src/main/java/org/apache/commons/collections4/FactoryUtils.java +++ b/src/main/java/org/apache/commons/collections4/FactoryUtils.java @@ -94,11 +94,12 @@ public class FactoryUtils { * Creates a Factory that will return a clone of the same prototype object * each time the factory is used. The prototype will be cloned using one of these * techniques (in order): + * *

    - *
  • public clone method - *
  • public copy constructor - *
  • serialization clone - *
      + *
    • public clone method
      • + *
    • public copy constructor
      • + *
    • serialization clone
      • + *
    * * @see org.apache.commons.collections4.functors.PrototypeFactory * diff --git a/src/main/java/org/apache/commons/collections4/FluentIterable.java b/src/main/java/org/apache/commons/collections4/FluentIterable.java index b6de3c015..d8563bfab 100644 --- a/src/main/java/org/apache/commons/collections4/FluentIterable.java +++ b/src/main/java/org/apache/commons/collections4/FluentIterable.java @@ -47,7 +47,7 @@ import org.apache.commons.collections4.iterators.SingletonIterator; * List<String> result = * FluentIterable * .of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) - * .filter(new Predicate() { + * .filter(new Predicate<Integer>() { * public boolean evaluate(Integer number) { * return number % 2 == 0; * } @@ -192,7 +192,7 @@ public class FluentIterable implements Iterable { * @param other the other iterable to collate, may not be null * @return a new iterable, collating this iterable with the other in natural order * @throws NullPointerException if other is null - * @see {@link org.apache.commons.collections4.iterators.CollatingIterator CollatingIterator} + * @see org.apache.commons.collections4.iterators.CollatingIterator */ public FluentIterable collate(final Iterable other) { return of(IterableUtils.collatedIterable(iterable, other)); @@ -217,7 +217,7 @@ public class FluentIterable implements Iterable { * @param other the other iterable to collate, may not be null * @return a new iterable, collating this iterable with the other in natural order * @throws NullPointerException if other is null - * @see {@link org.apache.commons.collections4.iterators.CollatingIterator CollatingIterator} + * @see org.apache.commons.collections4.iterators.CollatingIterator */ public FluentIterable collate(final Iterable other, final Comparator comparator) { @@ -231,7 +231,7 @@ public class FluentIterable implements Iterable { *

    * Calling this method is equivalent to: * 

    -     *   FluentIterable someIterable = ...;
+     *   FluentIterable<E> someIterable = ...;
      *   FluentIterable.of(someIterable.toList());
      *
    * diff --git a/src/main/java/org/apache/commons/collections4/Get.java b/src/main/java/org/apache/commons/collections4/Get.java index 5508ba78a..7a1c8fa73 100644 --- a/src/main/java/org/apache/commons/collections4/Get.java +++ b/src/main/java/org/apache/commons/collections4/Get.java @@ -30,46 +30,63 @@ import java.util.Set; public interface Get { /** + * @param key key whose presence in this map is to be tested + * @return true if this map contains a mapping for the specified + * key * @see java.util.Map#containsKey(Object) */ boolean containsKey(Object key); /** + * @param value value whose presence in this map is to be tested + * @return true if this map maps one or more keys to the + * specified value * @see java.util.Map#containsValue(Object) */ boolean containsValue(Object value); /** + * @return a set view of the mappings contained in this map * @see java.util.Map#entrySet() */ Set> entrySet(); /** + * @param key the key whose associated value is to be returned + * @return the value to which the specified key is mapped, or + * {@code null} if this map contains no mapping for the key * @see java.util.Map#get(Object) */ V get(Object key); /** + * @param key key whose mapping is to be removed from the map + * @return the previous value associated with key, or + * null if there was no mapping for key. * @see java.util.Map#remove(Object) */ V remove(Object key); /** + * @return true if this map contains no key-value mappings * @see java.util.Map#isEmpty() */ boolean isEmpty(); /** + * @return a set view of the keys contained in this map * @see java.util.Map#keySet() */ Set keySet(); /** + * @return the number of key-value mappings in this map * @see java.util.Map#size() */ int size(); /** + * @return a collection view of the values contained in this map * @see java.util.Map#values() */ Collection values(); diff --git a/src/main/java/org/apache/commons/collections4/IterableGet.java b/src/main/java/org/apache/commons/collections4/IterableGet.java index 1edde5ae7..41fece02f 100644 --- a/src/main/java/org/apache/commons/collections4/IterableGet.java +++ b/src/main/java/org/apache/commons/collections4/IterableGet.java @@ -31,8 +31,8 @@ public interface IterableGet extends Get { * A map iterator is an efficient way of iterating over maps. * There is no need to access the entry set or use Map Entry objects. * 
    -     * IterableMap map = new HashedMap();
-     * MapIterator it = map.mapIterator();
+     * IterableMap<String,Integer> map = new HashedMap<String,Integer>();
+     * MapIterator<String,Integer> it = map.mapIterator();
      * while (it.hasNext()) {
      *   String key = it.next();
      *   Integer value = it.getValue();
diff --git a/src/main/java/org/apache/commons/collections4/IterableMap.java b/src/main/java/org/apache/commons/collections4/IterableMap.java
index 9169561b0..79f72388f 100644
--- a/src/main/java/org/apache/commons/collections4/IterableMap.java
+++ b/src/main/java/org/apache/commons/collections4/IterableMap.java
@@ -24,8 +24,8 @@ import java.util.Map;
  * A map iterator is an efficient way of iterating over maps.
  * There is no need to access the entry set or use Map Entry objects.
  * 
    - * IterableMap map = new HashedMap();
- * MapIterator it = map.mapIterator();
+ * IterableMap<String,Integer> map = new HashedMap<String,Integer>();
+ * MapIterator<String,Integer> it = map.mapIterator();
  * while (it.hasNext()) {
  *   String key = it.next();
  *   Integer value = it.getValue();
diff --git a/src/main/java/org/apache/commons/collections4/MapUtils.java b/src/main/java/org/apache/commons/collections4/MapUtils.java
index c11437eb6..0ae9dba67 100644
--- a/src/main/java/org/apache/commons/collections4/MapUtils.java
+++ b/src/main/java/org/apache/commons/collections4/MapUtils.java
@@ -1765,7 +1765,7 @@ public class MapUtils {
      * @param   the key type
      * @param   the value type
      * @param map to wrap if necessary.
-     * @return IterableMap
+     * @return IterableMap<K, V>
      * @throws NullPointerException if map is null
      * @since 4.0
      */
@@ -1782,7 +1782,7 @@ public class MapUtils {
      * @param   the key type
      * @param   the value type
      * @param sortedMap to wrap if necessary
-     * @return {@link IterableSortedMap}
+     * @return {@link IterableSortedMap}<K, V>
      * @throws NullPointerException if sortedMap is null
      * @since 4.0
      */
diff --git a/src/main/java/org/apache/commons/collections4/Put.java b/src/main/java/org/apache/commons/collections4/Put.java
index fbd397101..b99f8b580 100644
--- a/src/main/java/org/apache/commons/collections4/Put.java
+++ b/src/main/java/org/apache/commons/collections4/Put.java
@@ -43,11 +43,19 @@ public interface Put {
      * Note that the return type is Object, rather than V as in the Map interface.
      * See the class Javadoc for further info.
      *
+     * @param key key with which the specified value is to be associated
+     * @param value value to be associated with the specified key
+     * @return the previous value associated with key, or
+     *         null if there was no mapping for key.
+     *         (A null return can also indicate that the map
+     *         previously associated null with key,
+     *         if the implementation supports null values.)
      * @see Map#put(Object, Object)
      */
     Object put(K key, V value);
 
     /**
+     * @param t mappings to be stored in this map
      * @see Map#putAll(Map)
      */
     void putAll(Map t);
diff --git a/src/main/java/org/apache/commons/collections4/SetUtils.java b/src/main/java/org/apache/commons/collections4/SetUtils.java
index 5d305c273..3777fe842 100644
--- a/src/main/java/org/apache/commons/collections4/SetUtils.java
+++ b/src/main/java/org/apache/commons/collections4/SetUtils.java
@@ -163,10 +163,10 @@ public class SetUtils {
      * Returns a new hash set that matches elements based on == not
      * equals().
      * 
    
-     * This set will violate the detail of various Set contracts.
+     * This set will violate the detail of various Set contracts.
      * As a general rule, don't compare this set to other sets. In particular, you can't
      * use decorators like {@link ListOrderedSet} on it, which silently assume that these
-     * contracts are fulfilled.
+     * contracts are fulfilled.
      * 
    
      * Note that the returned set is not synchronized and is not thread-safe.
      * If you wish to use this set from multiple threads concurrently, you must use
diff --git a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java
index 178090cd9..364f82f98 100644
--- a/src/main/java/org/apache/commons/collections4/SortedBidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/SortedBidiMap.java
@@ -53,7 +53,7 @@ public interface SortedBidiMap extends OrderedBidiMap, SortedMap
+     * @return Comparator<? super V>
      */
     Comparator valueComparator();
 }
diff --git a/src/main/java/org/apache/commons/collections4/TransformerUtils.java b/src/main/java/org/apache/commons/collections4/TransformerUtils.java
index a68556bca..9ecf42616 100644
--- a/src/main/java/org/apache/commons/collections4/TransformerUtils.java
+++ b/src/main/java/org/apache/commons/collections4/TransformerUtils.java
@@ -117,10 +117,10 @@ public class TransformerUtils {
      * Gets a transformer that returns a clone of the input object.
      * The input object will be cloned using one of these techniques (in order):
      * 
      
-     * 
    • public clone method
-     * 
    • public copy constructor
-     * 
    • serialization clone
-     * 
        
+     * 
      • public clone method
        • 
+     * 
      • public copy constructor
        • 
+     * 
      • serialization clone
        • 
+     * 
      
      *
      * @param   the input/output type
      * @return the transformer
@@ -267,7 +267,7 @@ public class TransformerUtils {
      * @return the transformer
      * @throws NullPointerException if either the predicate or transformer is null
      * @see SwitchTransformer
-     * @deprecated as of 4.1, use {@link #ifTransformer(Predicate, Transformer, Transformer))
+     * @deprecated as of 4.1, use {@link #ifTransformer(Predicate, Transformer, Transformer)}
      */
     @SuppressWarnings("unchecked")
     @Deprecated
@@ -430,12 +430,14 @@ public class TransformerUtils {
 
     /**
      * Gets a Transformer that invokes a method on the input object.
-     * The method must have no parameters. If the input object is null,
-     * null is returned.
+     * The method must have no parameters. If the input object is {@code null},
+     * {@code null} is returned.
+     *
      * 
      
      * For example, TransformerUtils.invokerTransformer("getName");
-     * will call the getName/code> method on the input object to
+     * will call the getName method on the input object to
      * determine the transformer result.
+     * 
      
      *
      * @param   the input type
      * @param   the output type
diff --git a/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java b/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
index 28c4b7dea..be6910a08 100644
--- a/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/CollectionBag.java
@@ -71,7 +71,7 @@ public final class CollectionBag extends AbstractBagDecorator {
      * Write the collection out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -82,8 +82,8 @@ public final class CollectionBag extends AbstractBagDecorator {
      * Read the collection in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @throws ClassCastException if deserialised object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
diff --git a/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java b/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
index 1baea2d35..ea2a9663e 100644
--- a/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/CollectionSortedBag.java
@@ -63,7 +63,7 @@ public final class CollectionSortedBag extends AbstractSortedBagDecorator
      * Write the collection out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -74,8 +74,8 @@ public final class CollectionSortedBag extends AbstractSortedBagDecorator
      * Read the collection in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @throws ClassCastException if deserialised object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
diff --git a/src/main/java/org/apache/commons/collections4/bag/HashBag.java b/src/main/java/org/apache/commons/collections4/bag/HashBag.java
index b2d64bb97..2f5e997d3 100644
--- a/src/main/java/org/apache/commons/collections4/bag/HashBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/HashBag.java
@@ -61,6 +61,9 @@ public class HashBag extends AbstractMapBag implements Serializable {
     //-----------------------------------------------------------------------
     /**
      * Write the bag out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -69,6 +72,10 @@ public class HashBag extends AbstractMapBag implements Serializable {
 
     /**
      * Read the bag in using a custom routine.
+     *
+     * @param in  the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/bag/TreeBag.java b/src/main/java/org/apache/commons/collections4/bag/TreeBag.java
index 016d67e62..f0aeea6d4 100644
--- a/src/main/java/org/apache/commons/collections4/bag/TreeBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/TreeBag.java
@@ -120,6 +120,9 @@ public class TreeBag extends AbstractMapBag implements SortedBag, Seria
     //-----------------------------------------------------------------------
     /**
      * Write the bag out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -129,6 +132,10 @@ public class TreeBag extends AbstractMapBag implements SortedBag, Seria
 
     /**
      * Read the bag in using a custom routine.
+     *
+     * @param in  the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
index 0f500e414..a583dbcbf 100644
--- a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableBag.java
@@ -81,7 +81,7 @@ public final class UnmodifiableBag
      * Write the collection out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -92,8 +92,8 @@ public final class UnmodifiableBag
      * Read the collection in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @throws ClassCastException if deserialised object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
diff --git a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
index 3560f3eff..6761e58ab 100644
--- a/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
+++ b/src/main/java/org/apache/commons/collections4/bag/UnmodifiableSortedBag.java
@@ -78,7 +78,7 @@ public final class UnmodifiableSortedBag
      * Write the collection out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -89,8 +89,8 @@ public final class UnmodifiableSortedBag
      * Read the collection in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @throws ClassCastException if deserialised object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
diff --git a/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java b/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java
index 23adc3f77..b7a9c1d24 100644
--- a/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java
+++ b/src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java
@@ -1431,6 +1431,10 @@ public class TreeBidiMap, V extends Comparable>
 
     /**
      * Reads the content of the stream.
+     *
+     * @param stream the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked") // This will fail at runtime if the stream is incorrect
     private void readObject(final ObjectInputStream stream) throws IOException, ClassNotFoundException{
@@ -1446,6 +1450,9 @@ public class TreeBidiMap, V extends Comparable>
 
     /**
      * Writes the content to the stream for serialization.
+     *
+     * @param stream  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream stream) throws IOException{
         stream.defaultWriteObject();
diff --git a/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java b/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java
index 3525b76b9..6f2256f05 100644
--- a/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java
+++ b/src/main/java/org/apache/commons/collections4/collection/CompositeCollection.java
@@ -415,7 +415,7 @@ public class CompositeCollection implements Collection, Serializable {
 
     /**
      * Get the collection mutator to be used for this CompositeCollection.
-     * @return CollectionMutator
+     * @return CollectionMutator<E>
      */
     protected CollectionMutator getMutator() {
         return mutator;
diff --git a/src/main/java/org/apache/commons/collections4/comparators/BooleanComparator.java b/src/main/java/org/apache/commons/collections4/comparators/BooleanComparator.java
index e8e9a7670..f0231a0db 100644
--- a/src/main/java/org/apache/commons/collections4/comparators/BooleanComparator.java
+++ b/src/main/java/org/apache/commons/collections4/comparators/BooleanComparator.java
@@ -48,12 +48,13 @@ public final class BooleanComparator implements Comparator, Serializabl
     /**
      * Returns a BooleanComparator instance that sorts
      * true values before false values.
-     * 
      
+     * 
      
      * Clients are encouraged to use the value returned from
      * this method instead of constructing a new instance
      * to reduce allocation and garbage collection overhead when
      * multiple BooleanComparators may be used in the same
      * virtual machine.
+     * 
      
      *
      * @return the true first singleton BooleanComparator
      */
@@ -64,12 +65,13 @@ public final class BooleanComparator implements Comparator, Serializabl
     /**
      * Returns a BooleanComparator instance that sorts
      * false values before true values.
-     * 
      
+     * 
      
      * Clients are encouraged to use the value returned from
      * this method instead of constructing a new instance
      * to reduce allocation and garbage collection overhead when
      * multiple BooleanComparators may be used in the same
      * virtual machine.
+     * 
      
      *
      * @return the false first singleton BooleanComparator
      */
@@ -81,12 +83,13 @@ public final class BooleanComparator implements Comparator, Serializabl
      * Returns a BooleanComparator instance that sorts
      * trueFirst values before
      * !trueFirst values.
-     * 
      
+     * 
      
      * Clients are encouraged to use the value returned from
      * this method instead of constructing a new instance
      * to reduce allocation and garbage collection overhead when
      * multiple BooleanComparators may be used in the same
      * virtual machine.
+     * 
      
      *
      * @param trueFirst when true, sort
      * true Booleans before false
diff --git a/src/main/java/org/apache/commons/collections4/functors/CatchAndRethrowClosure.java b/src/main/java/org/apache/commons/collections4/functors/CatchAndRethrowClosure.java
index 38b7fe2fc..42a8e0f0b 100644
--- a/src/main/java/org/apache/commons/collections4/functors/CatchAndRethrowClosure.java
+++ b/src/main/java/org/apache/commons/collections4/functors/CatchAndRethrowClosure.java
@@ -34,7 +34,7 @@ import org.apache.commons.collections4.FunctorException;
  * };
  *
  * // use catch and re-throw closure
- * java.util.List strList = // some list
+ * java.util.List<String> strList = // some list
  * try {
  *     CollectionUtils.forAllDo(strList, writer);
  * } catch (FunctorException ex) {
diff --git a/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java b/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java
index fd1d8297c..4d5474d53 100644
--- a/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java
+++ b/src/main/java/org/apache/commons/collections4/functors/ComparatorPredicate.java
@@ -25,7 +25,7 @@ import org.apache.commons.collections4.Predicate;
  * Predicate that compares the input object with the one stored in the predicate using a comparator.
  * In addition, the comparator result can be evaluated in accordance to a supplied criterion value.
  *
- * In order to demonstrate the use of the predicate, the following variables are declared:
+ * 
      In order to demonstrate the use of the predicate, the following variables are declared:
      
  *
  * 
        * Integer ONE = Integer.valueOf(1);
@@ -40,14 +40,14 @@ import org.apache.commons.collections4.Predicate;
  * };
  * 
      
  *
- * Using the declared variables, the ComparatorPredicate can be used used in the
- * following way:
+ * 
      Using the declared variables, the ComparatorPredicate can be used used in the
+ * following way:
      
  *
  * 
        * ComparatorPredicate.comparatorPredicate(ONE, comparator).evaluate(TWO);
  * 
      
  *
- * The input variable TWO in compared to the stored variable ONE using
+ * 
      The input variable TWO in compared to the stored variable ONE using
  * the supplied comparator. This is the default usage of the predicate and will return
  * true if the underlying comparator returns 0. In addition to the default
  * usage of the predicate, it is possible to evaluate the comparator's result in several ways. The
@@ -62,16 +62,16 @@ import org.apache.commons.collections4.Predicate;
  *     
    • LESS_OR_EQUAL
      • 
  * 
    
  *
- * The following examples demonstrates how these constants can be used in order to manipulate the
- * evaluation of a comparator result.
+ * 
    The following examples demonstrates how these constants can be used in order to manipulate the
+ * evaluation of a comparator result.
    
  *
  * 
      * ComparatorPredicate.comparatorPredicate(ONE, comparator,ComparatorPredicate.Criterion.GREATER).evaluate(TWO);
  * 
    
  *
- * The input variable TWO is compared to the stored variable ONE using the supplied comparator
+ * 
    The input variable TWO is compared to the stored variable ONE using the supplied comparator
  * using the GREATER evaluation criterion constant. This instructs the predicate to
- * return true if the comparator returns a value greater than 0.
+ * return true if the comparator returns a value greater than 0.
    
  *
  * @since 4.0
  * @version $Id$
@@ -148,11 +148,11 @@ public class ComparatorPredicate implements Predicate, Serializable {
      * Evaluates the predicate. The predicate evaluates to true in the following cases:
      *
      * 
      
-     *     
    • comparator.compare(object, input) == 0 && criterion == EQUAL
      • 
-     *     
    • comparator.compare(object, input) < 0 && criterion == LESS
      • 
-     *     
    • comparator.compare(object, input) > 0 && criterion == GREATER
      • 
-     *     
    • comparator.compare(object, input) >= 0 && criterion == GREATER_OR_EQUAL
      • 
-     *     
    • comparator.compare(object, input) <= 0 && criterion == LESS_OR_EQUAL
      • 
+     * 
    • comparator.compare(object, input) == 0 && criterion == EQUAL
      • 
+     * 
    • comparator.compare(object, input) < 0 && criterion == LESS
      • 
+     * 
    • comparator.compare(object, input) > 0 && criterion == GREATER
      • 
+     * 
    • comparator.compare(object, input) >= 0 && criterion == GREATER_OR_EQUAL
      • 
+     * 
    • comparator.compare(object, input) <= 0 && criterion == LESS_OR_EQUAL
      • 
      * 
    
      *
      * @see org.apache.commons.collections4.Predicate#evaluate(java.lang.Object)
diff --git a/src/main/java/org/apache/commons/collections4/functors/ConstantTransformer.java b/src/main/java/org/apache/commons/collections4/functors/ConstantTransformer.java
index 30b99c52d..d10291aea 100644
--- a/src/main/java/org/apache/commons/collections4/functors/ConstantTransformer.java
+++ b/src/main/java/org/apache/commons/collections4/functors/ConstantTransformer.java
@@ -47,7 +47,7 @@ public class ConstantTransformer implements Transformer, Serializabl
      *
      * @param   the input type
      * @param   the output type
-     * @return Transformer that always returns null.
+     * @return Transformer<I, O> that always returns null.
      */
     @SuppressWarnings("unchecked") // The null transformer works for all object types
     public static  Transformer nullTransformer() {
diff --git a/src/main/java/org/apache/commons/collections4/functors/InstantiateTransformer.java b/src/main/java/org/apache/commons/collections4/functors/InstantiateTransformer.java
index 58fcf9d7d..6f68600e7 100644
--- a/src/main/java/org/apache/commons/collections4/functors/InstantiateTransformer.java
+++ b/src/main/java/org/apache/commons/collections4/functors/InstantiateTransformer.java
@@ -48,7 +48,7 @@ public class InstantiateTransformer implements Transformer
      * Get a typed no-arg instance.
      *
      * @param   the type of the objects to be created
-     * @return Transformer, T>
+     * @return Transformer<Class<? extends T>, T>
      */
     @SuppressWarnings("unchecked")
     public static  Transformer, T> instantiateTransformer() {
diff --git a/src/main/java/org/apache/commons/collections4/functors/PrototypeFactory.java b/src/main/java/org/apache/commons/collections4/functors/PrototypeFactory.java
index bde28780c..199f96b66 100644
--- a/src/main/java/org/apache/commons/collections4/functors/PrototypeFactory.java
+++ b/src/main/java/org/apache/commons/collections4/functors/PrototypeFactory.java
@@ -48,11 +48,13 @@ public class PrototypeFactory {
      * Creates a Factory that will return a clone of the same prototype object
      * each time the factory is used. The prototype will be cloned using one of these
      * techniques (in order):
+     * 
    
+     *
      * 
      
-     * 
    • public clone method
-     * 
    • public copy constructor
-     * 
    • serialization clone
-     * 
        
+     * 
      • public clone method
        • 
+     * 
      • public copy constructor
        • 
+     * 
      • serialization clone
        • 
+     * 
      
      *
      * @param   the type the factory creates
      * @param prototype  the object to clone each time in the factory
diff --git a/src/main/java/org/apache/commons/collections4/iterators/ArrayListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/ArrayListIterator.java
index b5307d637..e6743cec9 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/ArrayListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/ArrayListIterator.java
@@ -22,7 +22,7 @@ import java.util.NoSuchElementException;
 import org.apache.commons.collections4.ResettableListIterator;
 
 /**
- * Implements a {@link ListIterator} over an array.
+ * Implements a {@link java.util.ListIterator} over an array.
  * 
      
  * The array can be either an array of object or of primitives. If you know
  * that you have an object array, the {@link ObjectArrayListIterator}
@@ -177,9 +177,9 @@ public class ArrayListIterator extends ArrayIterator
      * This method sets the element that was returned by the last call
      * to {@link #next()} of {@link #previous()}.
      * 
      
-     * Note: {@link ListIterator} implementations that support
+     * Note: {@link java.util.ListIterator} implementations that support
      * add() and remove() only allow set() to be called
-     * once per call to next() or previous (see the {@link ListIterator}
+     * once per call to next() or previous (see the {@link java.util.ListIterator}
      * javadoc for more details). Since this implementation does
      * not support add() or remove(), set() may be
      * called as often as desired.
diff --git a/src/main/java/org/apache/commons/collections4/iterators/EmptyIterator.java b/src/main/java/org/apache/commons/collections4/iterators/EmptyIterator.java
index 6f5b0c99c..3d1ee3656 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/EmptyIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/EmptyIterator.java
@@ -49,7 +49,7 @@ public class EmptyIterator extends AbstractEmptyIterator implements Resett
     /**
      * Get a typed resettable empty iterator instance.
      * @param  the element type
-     * @return ResettableIterator
+     * @return ResettableIterator<E>
      */
     @SuppressWarnings("unchecked")
     public static  ResettableIterator resettableEmptyIterator() {
@@ -59,7 +59,7 @@ public class EmptyIterator extends AbstractEmptyIterator implements Resett
     /**
      * Get a typed empty iterator instance.
      * @param  the element type
-     * @return Iterator
+     * @return Iterator<E>
      */
     @SuppressWarnings("unchecked")
     public static  Iterator emptyIterator() {
diff --git a/src/main/java/org/apache/commons/collections4/iterators/EmptyListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/EmptyListIterator.java
index 6c6f8b413..909afa07e 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/EmptyListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/EmptyListIterator.java
@@ -50,7 +50,7 @@ public class EmptyListIterator extends AbstractEmptyIterator implements
     /**
      * Get a typed instance of the iterator.
      * @param  the element type
-     * @return {@link ResettableListIterator}
+     * @return {@link ResettableListIterator}<E>
      */
     @SuppressWarnings("unchecked")
     public static  ResettableListIterator resettableEmptyListIterator() {
@@ -60,7 +60,7 @@ public class EmptyListIterator extends AbstractEmptyIterator implements
     /**
      * Get a typed instance of the iterator.
      * @param  the element type
-     * @return {@link ListIterator}
+     * @return {@link ListIterator}<E>
      */
     @SuppressWarnings("unchecked")
     public static  ListIterator emptyListIterator() {
diff --git a/src/main/java/org/apache/commons/collections4/iterators/EmptyMapIterator.java b/src/main/java/org/apache/commons/collections4/iterators/EmptyMapIterator.java
index 90fee4a2e..813d58292 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/EmptyMapIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/EmptyMapIterator.java
@@ -39,7 +39,7 @@ public class EmptyMapIterator extends AbstractEmptyMapIterator imple
      * Get a typed instance of the iterator.
      * @param  the key type
      * @param  the value type
-     * @return {@link MapIterator}
+     * @return {@link MapIterator}<K, V>
      */
     @SuppressWarnings("unchecked")
     public static  MapIterator emptyMapIterator() {
diff --git a/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedIterator.java b/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedIterator.java
index 200cae90f..bfc292984 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedIterator.java
@@ -38,7 +38,7 @@ public class EmptyOrderedIterator extends AbstractEmptyIterator
     /**
      * Typed instance of the iterator.
      * @param  the element type
-     * @return OrderedIterator
+     * @return OrderedIterator<E>
      */
     @SuppressWarnings("unchecked")
     public static  OrderedIterator emptyOrderedIterator() {
diff --git a/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedMapIterator.java b/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedMapIterator.java
index 6a5023b1d..dc5654e20 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedMapIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/EmptyOrderedMapIterator.java
@@ -39,7 +39,7 @@ public class EmptyOrderedMapIterator extends AbstractEmptyMapIterator the key type
      * @param  the value type
-     * @return {@link OrderedMapIterator}
+     * @return {@link OrderedMapIterator}<K, V>
      */
     @SuppressWarnings("unchecked")
     public static  OrderedMapIterator emptyOrderedMapIterator() {
diff --git a/src/main/java/org/apache/commons/collections4/iterators/FilterListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/FilterListIterator.java
index 6bd0e4306..15e513eff 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/FilterListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/FilterListIterator.java
@@ -112,7 +112,10 @@ public class FilterListIterator implements ListIterator {
     }
 
     //-----------------------------------------------------------------------
-    /** Not supported. */
+    /**
+     * Not supported.
+     * @param o the element to insert
+     */
     @Override
     public void add(final E o) {
         throw new UnsupportedOperationException("FilterListIterator.add(Object) is not supported.");
@@ -170,7 +173,11 @@ public class FilterListIterator implements ListIterator {
         throw new UnsupportedOperationException("FilterListIterator.remove() is not supported.");
     }
 
-    /** Not supported. */
+    /**
+     * Not supported.
+     * @param o the element with which to replace the last element returned by
+     *          {@code next} or {@code previous}
+     */
     @Override
     public void set(final E o) {
         throw new UnsupportedOperationException("FilterListIterator.set(Object) is not supported.");
diff --git a/src/main/java/org/apache/commons/collections4/iterators/IteratorIterable.java b/src/main/java/org/apache/commons/collections4/iterators/IteratorIterable.java
index b26e08963..59c6eddf5 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/IteratorIterable.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/IteratorIterable.java
@@ -28,35 +28,38 @@ import org.apache.commons.collections4.ResettableIterator;
  * operations use the same, exhausted source iterator.  To create a single use
  * iterable, construct a new {@link IteratorIterable} using a {@link Iterator}
  * that is NOT a {@link ResettableIterator} iterator:
- * 
      - *   Iterator iterator = // some non-resettable iterator
- *   Iterable iterable = new IteratorIterable(iterator);
- * 
      
  * 
      
  *
+ * 
      + *   Iterator<Integer> iterator = // some non-resettable iterator
+ *   Iterable<Integer> iterable = new IteratorIterable<Integer>(iterator);
+ * 
      
+ *
  * 
      
  * In the multiple use iterable case, the iterable is usable for any number of
  * iterative operations over the source iterator.  Of special note, even though
  * the iterable supports multiple iterations, it does not support concurrent
  * iterations. To implicitly create a multiple use iterable, construct a new
  * {@link IteratorIterable} using a {@link ResettableIterator} iterator:
+ * 
      
+ *
  * 
        *   Integer[] array = {Integer.valueOf(1),Integer.valueOf(2),Integer.valueOf(3)};
- *   Iterator iterator = IteratorUtils.arrayIterator(array); // a resettable iterator
- *   Iterable iterable = new IteratorIterable(iterator);
+ *   Iterator<Integer> iterator = IteratorUtils.arrayIterator(array); // a resettable iterator
+ *   Iterable<Integer> iterable = new IteratorIterable<Integer>(iterator);
  * 
      
- * 
      
  *
  * 
      
  * A multiple use iterable can also be explicitly constructed using any
  * {@link Iterator} and specifying true for the
  * multipleUse flag:
- * 
      - *   Iterator iterator = // some non-resettable iterator
- *   Iterable iterable = new IteratorIterable(iterator, true);
- * 
      
  * 
      
  *
+ * 
      + *   Iterator<Integer> iterator = // some non-resettable iterator
+ *   Iterable<Integer> iterable = new IteratorIterable<Integer>(iterator, true);
+ * 
      
+ *
  * @since 4.0
  * @version $Id$
  */
diff --git a/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java
index b107f6ec7..c6196efa0 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/ObjectArrayListIterator.java
@@ -21,7 +21,7 @@ import java.util.NoSuchElementException;
 import org.apache.commons.collections4.ResettableListIterator;
 
 /**
- * Implements a {@link ListIterator} over an array of objects.
+ * Implements a {@link java.util.ListIterator} over an array of objects.
  * 
      
  * This iterator does not support {@link #add} or {@link #remove}, as the object array
  * cannot be structurally modified. The {@link #set} method is supported however.
@@ -168,9 +168,9 @@ public class ObjectArrayListIterator extends ObjectArrayIterator
      * This method sets the element that was returned by the last call
      * to {@link #next()} of {@link #previous()}.
      *
-     * Note: {@link ListIterator} implementations that support add()
+     * Note: {@link java.util.ListIterator} implementations that support add()
      * and remove() only allow set() to be called once per call
-     * to next() or previous (see the {@link ListIterator}
+     * to next() or previous (see the {@link java.util.ListIterator}
      * javadoc for more details). Since this implementation does not support
      * add() or remove(), set() may be
      * called as often as desired.
diff --git a/src/main/java/org/apache/commons/collections4/iterators/SingletonIterator.java b/src/main/java/org/apache/commons/collections4/iterators/SingletonIterator.java
index df15e8bd1..2941a8143 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/SingletonIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/SingletonIterator.java
@@ -21,7 +21,7 @@ import java.util.NoSuchElementException;
 import org.apache.commons.collections4.ResettableIterator;
 
 /**
- * SingletonIterator is an {@link Iterator} over a single
+ * SingletonIterator is an {@link java.util.Iterator} over a single
  * object instance.
  *
  * @since 2.0
diff --git a/src/main/java/org/apache/commons/collections4/iterators/SingletonListIterator.java b/src/main/java/org/apache/commons/collections4/iterators/SingletonListIterator.java
index 5dab9b836..736132ee6 100644
--- a/src/main/java/org/apache/commons/collections4/iterators/SingletonListIterator.java
+++ b/src/main/java/org/apache/commons/collections4/iterators/SingletonListIterator.java
@@ -21,7 +21,7 @@ import java.util.NoSuchElementException;
 import org.apache.commons.collections4.ResettableListIterator;
 
 /**
- * SingletonIterator is an {@link ListIterator} over a single
+ * SingletonIterator is an {@link java.util.ListIterator} over a single
  * object instance.
  *
  * @since 2.1
diff --git a/src/main/java/org/apache/commons/collections4/list/AbstractSerializableListDecorator.java b/src/main/java/org/apache/commons/collections4/list/AbstractSerializableListDecorator.java
index 2afd8bb1b..61dc970b5 100644
--- a/src/main/java/org/apache/commons/collections4/list/AbstractSerializableListDecorator.java
+++ b/src/main/java/org/apache/commons/collections4/list/AbstractSerializableListDecorator.java
@@ -49,7 +49,7 @@ public abstract class AbstractSerializableListDecorator
      * Write the list out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -60,8 +60,8 @@ public abstract class AbstractSerializableListDecorator
      * Read the list in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked")
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
diff --git a/src/main/java/org/apache/commons/collections4/list/CursorableLinkedList.java b/src/main/java/org/apache/commons/collections4/list/CursorableLinkedList.java
index 101bf43a5..46c504e17 100644
--- a/src/main/java/org/apache/commons/collections4/list/CursorableLinkedList.java
+++ b/src/main/java/org/apache/commons/collections4/list/CursorableLinkedList.java
@@ -363,6 +363,9 @@ public class CursorableLinkedList extends AbstractLinkedList implements Se
     //-----------------------------------------------------------------------
     /**
      * Serializes the data held in this object to the stream specified.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -371,6 +374,10 @@ public class CursorableLinkedList extends AbstractLinkedList implements Se
 
     /**
      * Deserializes the data held in this object to the stream specified.
+     *
+     * @param in  the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/list/NodeCachingLinkedList.java b/src/main/java/org/apache/commons/collections4/list/NodeCachingLinkedList.java
index eb919c74a..bb5fd2cd0 100644
--- a/src/main/java/org/apache/commons/collections4/list/NodeCachingLinkedList.java
+++ b/src/main/java/org/apache/commons/collections4/list/NodeCachingLinkedList.java
@@ -227,6 +227,9 @@ public class NodeCachingLinkedList extends AbstractLinkedList implements S
     //-----------------------------------------------------------------------
     /**
      * Serializes the data held in this object to the stream specified.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -235,6 +238,10 @@ public class NodeCachingLinkedList extends AbstractLinkedList implements S
 
     /**
      * Deserializes the data held in this object to the stream specified.
+     *
+     * @param in  the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/map/AbstractInputCheckedMapDecorator.java b/src/main/java/org/apache/commons/collections4/map/AbstractInputCheckedMapDecorator.java
index a2b1959b8..0ba6d6eec 100644
--- a/src/main/java/org/apache/commons/collections4/map/AbstractInputCheckedMapDecorator.java
+++ b/src/main/java/org/apache/commons/collections4/map/AbstractInputCheckedMapDecorator.java
@@ -30,14 +30,17 @@ import org.apache.commons.collections4.set.AbstractSetDecorator;
  * 
      
  * The Map API is very difficult to decorate correctly, and involves implementing
  * lots of different classes. This class exists to provide a simpler API.
+ * 
      
  * 
      
  * Special hook methods are provided that are called when objects are added to
  * the map. By overriding these methods, the input can be validated or manipulated.
  * In addition to the main map methods, the entrySet is also affected, which is
  * the hardest part of writing map implementations.
+ * 
      
  * 
      
  * This class is package-scoped, and may be withdrawn or replaced in future
  * versions of Commons Collections.
+ * 
      
  *
  * @since 3.1
  * @version $Id$
@@ -68,10 +71,13 @@ abstract class AbstractInputCheckedMapDecorator
      * 
      
      * An implementation may validate the value and throw an exception
      * or it may transform the value into another object.
+     * 
      
      * 
      
      * This implementation returns the input value.
+     * 
      
      *
      * @param value  the value to check
+     * @return the input value
      * @throws UnsupportedOperationException if the map may not be changed by setValue
      * @throws IllegalArgumentException if the specified value is invalid
      * @throws ClassCastException if the class of the specified value is invalid
diff --git a/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java b/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
index d06d5cb35..0d6967ee8 100644
--- a/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/AbstractLinkedMap.java
@@ -75,7 +75,7 @@ public abstract class AbstractLinkedMap extends AbstractHashedMap im
      * Constructor which performs no validation on the passed in parameters.
      *
      * @param initialCapacity  the initial capacity, must be a power of two
-     * @param loadFactor  the load factor, must be > 0.0f and generally < 1.0f
+     * @param loadFactor  the load factor, must be > 0.0f and generally < 1.0f
      * @param threshold  the threshold, must be sensible
      */
     protected AbstractLinkedMap(final int initialCapacity, final float loadFactor, final int threshold) {
diff --git a/src/main/java/org/apache/commons/collections4/map/CaseInsensitiveMap.java b/src/main/java/org/apache/commons/collections4/map/CaseInsensitiveMap.java
index bd6e2e4a9..176f6f3dc 100644
--- a/src/main/java/org/apache/commons/collections4/map/CaseInsensitiveMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/CaseInsensitiveMap.java
@@ -46,16 +46,18 @@ import java.util.Map;
  * returns "Four".  The Set returned by keySet()
  * equals {"one", "two", null}.
  * 
      
- * This map will violate the detail of various Map and map view contracts.
+ * This map will violate the detail of various Map and map view contracts.
  * As a general rule, don't compare this map to other maps. In particular, you can't
  * use decorators like {@link ListOrderedMap} on it, which silently assume that these
  * contracts are fulfilled.
+ * 
      
  * 
      
  * Note that CaseInsensitiveMap is not synchronized and is not thread-safe.
  * If you wish to use this map from multiple threads concurrently, you must use
  * appropriate synchronization. The simplest approach is to wrap this map
  * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw
  * exceptions when accessed by concurrent threads without synchronization.
+ * 
      
  *
  * @since 3.0
  * @version $Id$
@@ -144,6 +146,9 @@ public class CaseInsensitiveMap extends AbstractHashedMap implements
 
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -152,6 +157,10 @@ public class CaseInsensitiveMap extends AbstractHashedMap implements
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java b/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
index 47a1e8af0..faddcdf78 100644
--- a/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/DefaultedMap.java
@@ -174,7 +174,7 @@ public class DefaultedMap extends AbstractMapDecorator implements Se
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -185,8 +185,8 @@ public class DefaultedMap extends AbstractMapDecorator implements Se
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked")
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
diff --git a/src/main/java/org/apache/commons/collections4/map/EntrySetToMapIteratorAdapter.java b/src/main/java/org/apache/commons/collections4/map/EntrySetToMapIteratorAdapter.java
index 5b0e10fd7..d100a40d0 100644
--- a/src/main/java/org/apache/commons/collections4/map/EntrySetToMapIteratorAdapter.java
+++ b/src/main/java/org/apache/commons/collections4/map/EntrySetToMapIteratorAdapter.java
@@ -109,7 +109,7 @@ public class EntrySetToMapIteratorAdapter implements MapIterator, Re
 
     /**
      * Get the currently active entry.
-     * @return Map.Entry
+     * @return Map.Entry<K, V>
      */
     protected synchronized Map.Entry current() {
         if (entry == null) {
diff --git a/src/main/java/org/apache/commons/collections4/map/FixedSizeMap.java b/src/main/java/org/apache/commons/collections4/map/FixedSizeMap.java
index 4768b910f..b909aef70 100644
--- a/src/main/java/org/apache/commons/collections4/map/FixedSizeMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/FixedSizeMap.java
@@ -89,7 +89,7 @@ public class FixedSizeMap
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -101,8 +101,8 @@ public class FixedSizeMap
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
diff --git a/src/main/java/org/apache/commons/collections4/map/FixedSizeSortedMap.java b/src/main/java/org/apache/commons/collections4/map/FixedSizeSortedMap.java
index ac6feeb9e..f57e8e9d7 100644
--- a/src/main/java/org/apache/commons/collections4/map/FixedSizeSortedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/FixedSizeSortedMap.java
@@ -98,6 +98,9 @@ public class FixedSizeSortedMap
     //-----------------------------------------------------------------------
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -106,6 +109,10 @@ public class FixedSizeSortedMap
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
diff --git a/src/main/java/org/apache/commons/collections4/map/Flat3Map.java b/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
index 62d91f960..dcce62a7e 100644
--- a/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
+++ b/src/main/java/org/apache/commons/collections4/map/Flat3Map.java
@@ -1108,6 +1108,9 @@ public class Flat3Map implements IterableMap, Serializable, Cloneabl
     //-----------------------------------------------------------------------
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -1120,6 +1123,10 @@ public class Flat3Map implements IterableMap, Serializable, Cloneabl
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked")
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
diff --git a/src/main/java/org/apache/commons/collections4/map/HashedMap.java b/src/main/java/org/apache/commons/collections4/map/HashedMap.java
index fb6863a0f..9c66adcb2 100644
--- a/src/main/java/org/apache/commons/collections4/map/HashedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/HashedMap.java
@@ -98,6 +98,9 @@ public class HashedMap
 
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -106,6 +109,10 @@ public class HashedMap
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/map/LRUMap.java b/src/main/java/org/apache/commons/collections4/map/LRUMap.java
index b7c2dc8e3..e05d26df9 100644
--- a/src/main/java/org/apache/commons/collections4/map/LRUMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/LRUMap.java
@@ -198,8 +198,8 @@ public class LRUMap
 
     /**
      * Constructor copying elements from another map.
-     * 
      
-     * The maximum size is set from the map's size.
+     *
+     * 
      The maximum size is set from the map's size.
      
      *
      * @param map  the map to copy
      * @param scanUntilRemovable  scan until a removeable entry is found, default false
@@ -482,6 +482,9 @@ public class LRUMap
 
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -490,6 +493,10 @@ public class LRUMap
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/map/LazyMap.java b/src/main/java/org/apache/commons/collections4/map/LazyMap.java
index e254f089a..b46a156da 100644
--- a/src/main/java/org/apache/commons/collections4/map/LazyMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/LazyMap.java
@@ -133,7 +133,7 @@ public class LazyMap extends AbstractMapDecorator implements Seriali
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -145,8 +145,8 @@ public class LazyMap extends AbstractMapDecorator implements Seriali
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked")
diff --git a/src/main/java/org/apache/commons/collections4/map/LinkedMap.java b/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
index d025282de..6c5db902c 100644
--- a/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/LinkedMap.java
@@ -118,6 +118,9 @@ public class LinkedMap extends AbstractLinkedMap implements Serializ
 
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -126,6 +129,10 @@ public class LinkedMap extends AbstractLinkedMap implements Serializ
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java b/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
index 4511e0185..b8de298fd 100644
--- a/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/ListOrderedMap.java
@@ -128,7 +128,7 @@ public class ListOrderedMap
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -140,8 +140,8 @@ public class ListOrderedMap
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
diff --git a/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java b/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
index be4ccbf52..093e74f72 100644
--- a/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/MultiKeyMap.java
@@ -885,7 +885,7 @@ public class MultiKeyMap extends AbstractMapDecorator extends AbstractMapDecorator extends AbstractMapDecorator impleme
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 4.0
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -168,8 +168,8 @@ public class MultiValueMap extends AbstractMapDecorator impleme
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 4.0
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
diff --git a/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java b/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
index b7343d34e..8ba588a90 100644
--- a/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PassiveExpiringMap.java
@@ -504,8 +504,8 @@ public class PassiveExpiringMap
      * Read the map in using a custom routine.
      *
      * @param in the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked")
     // (1) should only fail if input stream is incorrect
@@ -519,7 +519,7 @@ public class PassiveExpiringMap
      * Write the map out using a custom routine.
      *
      * @param out the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out)
         throws IOException {
diff --git a/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java b/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
index 948cd7323..b8fd06e9e 100644
--- a/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/PredicatedMap.java
@@ -108,7 +108,7 @@ public class PredicatedMap
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -120,8 +120,8 @@ public class PredicatedMap
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
diff --git a/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java b/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
index 976a16d1f..8eafcd2e1 100644
--- a/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/ReferenceIdentityMap.java
@@ -27,41 +27,48 @@ import java.lang.ref.Reference;
  * removed by the garbage collector and matches keys and values based
  * on == not equals().
  * 
      
- * 
      
  * When you construct a ReferenceIdentityMap, you can specify what kind
  * of references are used to store the map's keys and values.
  * If non-hard references are used, then the garbage collector can remove
  * mappings if a key or value becomes unreachable, or if the JVM's memory is
  * running low. For information on how the different reference types behave,
  * see {@link Reference}.
+ * 
      
  * 
      
  * Different types of references can be specified for keys and values.
  * The default constructor uses hard keys and soft values, providing a
  * memory-sensitive cache.
+ * 
      
  * 
      
  * This map is similar to
  * {@link org.apache.commons.collections4.map.ReferenceMap ReferenceMap}.
  * It differs in that keys and values in this class are compared using ==.
+ * 
      
  * 
      
  * This map will violate the detail of various Map and map view contracts.
  * As a general rule, don't compare this map to other maps.
+ * 
      
  * 
      
  * This {@link java.util.Map Map} implementation does not allow null elements.
  * Attempting to add a null key or value to the map will raise a NullPointerException.
+ * 
      
  * 
      
  * This implementation is not synchronized.
  * You can use {@link java.util.Collections#synchronizedMap} to
  * provide synchronized access to a ReferenceIdentityMap.
  * Remember that synchronization will not stop the garbage collector removing entries.
+ * 
      
  * 
      
  * All the available iterators can be reset back to the start by casting to
  * ResettableIterator and calling reset().
+ * 
      
  * 
      
  * Note that ReferenceIdentityMap is not synchronized and is not thread-safe.
  * If you wish to use this map from multiple threads concurrently, you must use
  * appropriate synchronization. The simplest approach is to wrap this map
  * using {@link java.util.Collections#synchronizedMap}. This class may throw
  * exceptions when accessed by concurrent threads without synchronization.
+ * 
      
  *
  * @see java.lang.ref.Reference
  *
@@ -223,6 +230,9 @@ public class ReferenceIdentityMap extends AbstractReferenceMap imple
     //-----------------------------------------------------------------------
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -231,6 +241,10 @@ public class ReferenceIdentityMap extends AbstractReferenceMap imple
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/map/ReferenceMap.java b/src/main/java/org/apache/commons/collections4/map/ReferenceMap.java
index af5e0cea5..66f919ea2 100644
--- a/src/main/java/org/apache/commons/collections4/map/ReferenceMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/ReferenceMap.java
@@ -167,6 +167,9 @@ public class ReferenceMap extends AbstractReferenceMap implements Se
     //-----------------------------------------------------------------------
     /**
      * Write the map out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -175,6 +178,10 @@ public class ReferenceMap extends AbstractReferenceMap implements Se
 
     /**
      * Read the map in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/map/TransformedMap.java b/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
index 4a88259b4..c8715a3d2 100644
--- a/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/TransformedMap.java
@@ -132,7 +132,7 @@ public class TransformedMap
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -144,8 +144,8 @@ public class TransformedMap
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
diff --git a/src/main/java/org/apache/commons/collections4/map/UnmodifiableMap.java b/src/main/java/org/apache/commons/collections4/map/UnmodifiableMap.java
index 6237b7896..1348aa6bb 100644
--- a/src/main/java/org/apache/commons/collections4/map/UnmodifiableMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/UnmodifiableMap.java
@@ -85,7 +85,7 @@ public final class UnmodifiableMap
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -97,8 +97,8 @@ public final class UnmodifiableMap
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked")
diff --git a/src/main/java/org/apache/commons/collections4/map/UnmodifiableOrderedMap.java b/src/main/java/org/apache/commons/collections4/map/UnmodifiableOrderedMap.java
index c180a23d4..4d5d23bce 100644
--- a/src/main/java/org/apache/commons/collections4/map/UnmodifiableOrderedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/UnmodifiableOrderedMap.java
@@ -83,7 +83,7 @@ public final class UnmodifiableOrderedMap extends AbstractOrderedMapDecora
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -95,8 +95,8 @@ public final class UnmodifiableOrderedMap extends AbstractOrderedMapDecora
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
diff --git a/src/main/java/org/apache/commons/collections4/map/UnmodifiableSortedMap.java b/src/main/java/org/apache/commons/collections4/map/UnmodifiableSortedMap.java
index 78bfe8715..cafa29399 100644
--- a/src/main/java/org/apache/commons/collections4/map/UnmodifiableSortedMap.java
+++ b/src/main/java/org/apache/commons/collections4/map/UnmodifiableSortedMap.java
@@ -83,7 +83,7 @@ public final class UnmodifiableSortedMap
      * Write the map out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      * @since 3.1
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
@@ -95,8 +95,8 @@ public final class UnmodifiableSortedMap
      * Read the map in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked")
diff --git a/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java b/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
index 5648df947..73ccf0799 100644
--- a/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/multiset/HashMultiSet.java
@@ -59,6 +59,9 @@ public class HashMultiSet extends AbstractMapMultiSet implements Serializa
     //-----------------------------------------------------------------------
     /**
      * Write the multiset out using a custom routine.
+     *
+     * @param out  the output stream
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -67,6 +70,10 @@ public class HashMultiSet extends AbstractMapMultiSet implements Serializa
 
     /**
      * Read the multiset in using a custom routine.
+     *
+     * @param in the input stream
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
         in.defaultReadObject();
diff --git a/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java b/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
index 53985214b..bd297b09b 100644
--- a/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/multiset/UnmodifiableMultiSet.java
@@ -78,7 +78,7 @@ public final class UnmodifiableMultiSet
      * Write the collection out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -89,8 +89,8 @@ public final class UnmodifiableMultiSet
      * Read the collection in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @throws ClassCastException if deserialised object has wrong type
      */
     @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
diff --git a/src/main/java/org/apache/commons/collections4/multiset/package-info.java b/src/main/java/org/apache/commons/collections4/multiset/package-info.java
index 573f14177..40378a10c 100644
--- a/src/main/java/org/apache/commons/collections4/multiset/package-info.java
+++ b/src/main/java/org/apache/commons/collections4/multiset/package-info.java
@@ -16,14 +16,12 @@
  */
 /**
  * This package contains implementations of the
- * {@link org.apache.commons.collections4.MultiSet MultiSet} and
- * {@link org.apache.commons.collections4.SortedMultiSet SortedMultiSet} interfaces.
+ * {@link org.apache.commons.collections4.MultiSet MultiSet} interface.
  * A multiset stores an object and a count of the number of occurrences of the object.
  * 
      
  * The following implementations are provided in the package:
  * 
        
  *   
      • HashMultiSet - implementation that uses a HashMap to store the data
- *   
      • TreeMultiSet - implementation that uses a TreeMap to store the data
  * 
      
  * 
      
  * The following decorators are provided in the package:
diff --git a/src/main/java/org/apache/commons/collections4/properties/SortedProperties.java b/src/main/java/org/apache/commons/collections4/properties/SortedProperties.java
index e5c9f1922..833263f49 100644
--- a/src/main/java/org/apache/commons/collections4/properties/SortedProperties.java
+++ b/src/main/java/org/apache/commons/collections4/properties/SortedProperties.java
@@ -31,7 +31,7 @@ import org.apache.commons.collections4.iterators.IteratorEnumeration;
  * 
      
  * Overrides {@link Properties#keys()} to sort keys. Allows other methods on the superclass to work with sorted keys.
  * 
      
- * 
+ *
  * @since 4.2
  */
 public class SortedProperties extends Properties {
diff --git a/src/main/java/org/apache/commons/collections4/sequence/CommandVisitor.java b/src/main/java/org/apache/commons/collections4/sequence/CommandVisitor.java
index ff216272b..6eda1ad64 100644
--- a/src/main/java/org/apache/commons/collections4/sequence/CommandVisitor.java
+++ b/src/main/java/org/apache/commons/collections4/sequence/CommandVisitor.java
@@ -97,7 +97,7 @@ package org.apache.commons.collections4.sequence;
  *   }
  *
  *   private void display(String commandName, Object object) {
- *     System.out.println(commandName + " " + object + " ->" + this);
+ *     System.out.println(commandName + " " + object + " ->" + this);
  *   }
  *
  *   public String toString() {
diff --git a/src/main/java/org/apache/commons/collections4/set/AbstractSerializableSetDecorator.java b/src/main/java/org/apache/commons/collections4/set/AbstractSerializableSetDecorator.java
index e8e74e376..ca4c69d6c 100644
--- a/src/main/java/org/apache/commons/collections4/set/AbstractSerializableSetDecorator.java
+++ b/src/main/java/org/apache/commons/collections4/set/AbstractSerializableSetDecorator.java
@@ -49,7 +49,7 @@ public abstract class AbstractSerializableSetDecorator
      * Write the set out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -60,8 +60,8 @@ public abstract class AbstractSerializableSetDecorator
      * Read the set in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked")
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
diff --git a/src/main/java/org/apache/commons/collections4/set/UnmodifiableNavigableSet.java b/src/main/java/org/apache/commons/collections4/set/UnmodifiableNavigableSet.java
index 3cf0ca8d2..6135572f7 100644
--- a/src/main/java/org/apache/commons/collections4/set/UnmodifiableNavigableSet.java
+++ b/src/main/java/org/apache/commons/collections4/set/UnmodifiableNavigableSet.java
@@ -159,7 +159,7 @@ public final class UnmodifiableNavigableSet
      * Write the collection out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -170,8 +170,8 @@ public final class UnmodifiableNavigableSet
      * Read the collection in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
diff --git a/src/main/java/org/apache/commons/collections4/set/UnmodifiableSortedSet.java b/src/main/java/org/apache/commons/collections4/set/UnmodifiableSortedSet.java
index 81d669cdc..9163a8151 100644
--- a/src/main/java/org/apache/commons/collections4/set/UnmodifiableSortedSet.java
+++ b/src/main/java/org/apache/commons/collections4/set/UnmodifiableSortedSet.java
@@ -130,7 +130,7 @@ public final class UnmodifiableSortedSet
      * Write the collection out using a custom routine.
      *
      * @param out  the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -141,8 +141,8 @@ public final class UnmodifiableSortedSet
      * Read the collection in using a custom routine.
      *
      * @param in  the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
diff --git a/src/main/java/org/apache/commons/collections4/splitmap/AbstractIterableGetMapDecorator.java b/src/main/java/org/apache/commons/collections4/splitmap/AbstractIterableGetMapDecorator.java
index 8aa11ddc0..fed3e0976 100644
--- a/src/main/java/org/apache/commons/collections4/splitmap/AbstractIterableGetMapDecorator.java
+++ b/src/main/java/org/apache/commons/collections4/splitmap/AbstractIterableGetMapDecorator.java
@@ -25,8 +25,8 @@ import org.apache.commons.collections4.MapIterator;
 import org.apache.commons.collections4.map.EntrySetToMapIteratorAdapter;
 
 /**
- * {@link IterableGet} that uses a {@link Map} for the
- * {@link org.apache.commons.collections4.Get Get} implementation.
+ * {@link IterableGet} that uses a {@link Map}<K, V> for the
+ * {@link org.apache.commons.collections4.Get Get}<K, V> implementation.
  *
  * @since 4.0
  * @version $Id$
@@ -111,7 +111,7 @@ public class AbstractIterableGetMapDecorator implements IterableGet
 
     /**
      * Get a MapIterator over this Get.
-     * @return MapIterator
+     * @return MapIterator<K, V>
      */
     @Override
     public MapIterator mapIterator() {
diff --git a/src/main/java/org/apache/commons/collections4/splitmap/TransformedSplitMap.java b/src/main/java/org/apache/commons/collections4/splitmap/TransformedSplitMap.java
index 38f779a2d..4ace0bca7 100644
--- a/src/main/java/org/apache/commons/collections4/splitmap/TransformedSplitMap.java
+++ b/src/main/java/org/apache/commons/collections4/splitmap/TransformedSplitMap.java
@@ -121,7 +121,7 @@ public class TransformedSplitMap extends AbstractIterableGetMapDecor
      * Write the map out using a custom routine.
      *
      * @param out the output stream
-     * @throws IOException
+     * @throws IOException if an error occurs while writing to the stream
      */
     private void writeObject(final ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
@@ -132,8 +132,8 @@ public class TransformedSplitMap extends AbstractIterableGetMapDecor
      * Read the map in using a custom routine.
      *
      * @param in the input stream
-     * @throws IOException
-     * @throws ClassNotFoundException
+     * @throws IOException if an error occurs while reading from the stream
+     * @throws ClassNotFoundException if an object read from the stream can not be loaded
      * @since 3.1
      */
     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
diff --git a/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java b/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java
index 3dd8d99a0..44259c817 100644
--- a/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java
+++ b/src/main/java/org/apache/commons/collections4/trie/AbstractPatriciaTrie.java
@@ -45,7 +45,7 @@ abstract class AbstractPatriciaTrie extends AbstractBitwiseTrie {
 
     private static final long serialVersionUID = 5155253417231339498L;
 
-    /** The root node of the {@link Trie}. */
+    /** The root node of the {@link org.apache.commons.collections4.Trie}. */
     private transient TrieEntry root = new TrieEntry<>(null, null, -1);
 
     /**
@@ -57,11 +57,11 @@ abstract class AbstractPatriciaTrie extends AbstractBitwiseTrie {
     private transient volatile Collection values;
     private transient volatile Set> entrySet;
 
-    /** The current size of the {@link Trie}. */
+    /** The current size of the {@link org.apache.commons.collections4.Trie}. */
     private transient int size = 0;
 
     /**
-     * The number of times this {@link Trie} has been modified.
+     * The number of times this {@link org.apache.commons.collections4.Trie} has been modified.
      * It's used to detect concurrent modifications and fail-fast the {@link Iterator}s.
      */
     protected transient int modCount = 0;
@@ -71,8 +71,8 @@ abstract class AbstractPatriciaTrie extends AbstractBitwiseTrie {
     }
 
     /**
-     * Constructs a new {@link org.apache.commons.collections4.Trie Trie} using the given
-     * {@link KeyAnalyzer} and initializes the {@link org.apache.commons.collections4.Trie Trie}
+     * Constructs a new {@link org.apache.commons.collections4.Trie org.apache.commons.collections4.Trie Trie}
+     * using the given {@link KeyAnalyzer} and initializes the {@link org.apache.commons.collections4.Trie Trie}
      * with the values from the provided {@link Map}.
      */
     protected AbstractPatriciaTrie(final KeyAnalyzer keyAnalyzer,
@@ -271,7 +271,7 @@ abstract class AbstractPatriciaTrie extends AbstractBitwiseTrie {
      * 
    • L = 1001100
      * 
      *
-     * If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
+     * If the {@link org.apache.commons.collections4.Trie} contained 'H' and 'L', a lookup of 'D' would
      * return 'L', because the XOR distance between D & L is smaller
      * than the XOR distance between D & H.
      *
@@ -300,7 +300,7 @@ abstract class AbstractPatriciaTrie extends AbstractBitwiseTrie {
      * 
    • L = 1001100
      * 
      *
-     * If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
+     * If the {@link org.apache.commons.collections4.Trie} contained 'H' and 'L', a lookup of 'D' would
      * return 'L', because the XOR distance between D & L is smaller
      * than the XOR distance between D & H.
      *
@@ -327,7 +327,7 @@ abstract class AbstractPatriciaTrie extends AbstractBitwiseTrie {
      * 
    • L = 1001100
      * 
      *
-     * If the {@link Trie} contained 'H' and 'L', a lookup of 'D' would
+     * If the {@link org.apache.commons.collections4.Trie} contained 'H' and 'L', a lookup of 'D' would
      * return 'L', because the XOR distance between D & L is smaller
      * than the XOR distance between D & H.
      *
@@ -1268,7 +1268,7 @@ abstract class AbstractPatriciaTrie extends AbstractBitwiseTrie {
     }
 
     /**
-     *  A {@link Trie} is a set of {@link TrieEntry} nodes.
+     *  A {@link org.apache.commons.collections4.Trie} is a set of {@link TrieEntry} nodes.
      */
     protected static class TrieEntry extends BasicEntry {
 
diff --git a/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java b/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java
index 88b8b7a0b..ac3b76341 100644
--- a/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java
+++ b/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java
@@ -24,10 +24,12 @@ import org.apache.commons.collections4.trie.analyzer.StringKeyAnalyzer;
  * Implementation of a PATRICIA Trie (Practical Algorithm to Retrieve Information
  * Coded in Alphanumeric).
  * 
      
- * A PATRICIA {@link Trie} is a compressed {@link Trie}. Instead of storing
- * all data at the edges of the {@link Trie} (and having empty internal nodes),
- * PATRICIA stores data in every node. This allows for very efficient traversal,
- * insert, delete, predecessor, successor, prefix, range, and {@link #select(Object)}
+ * A PATRICIA {@link org.apache.commons.collections4.Trie} is a compressed
+ * {@link org.apache.commons.collections4.Trie}. Instead of storing
+ * all data at the edges of the {@link org.apache.commons.collections4.Trie}
+ * (and having empty internal nodes), PATRICIA stores data in every node.
+ * This allows for very efficient traversal, insert, delete, predecessor,
+ * successor, prefix, range, and {@link #select(Object)}
  * operations. All operations are performed at worst in O(K) time, where K
  * is the number of bits in the largest item in the tree. In practice,
  * operations actually take O(A(K)) time, where A(K) is the average number of
@@ -38,15 +40,16 @@ import org.apache.commons.collections4.trie.analyzer.StringKeyAnalyzer;
  * K of them, described above) will perform a single bit comparison against
  * the given key, instead of comparing the entire key to another key.
  * 
      
- * The {@link Trie} can return operations in lexicographical order using the
- * 'prefixMap', 'submap', or 'iterator' methods. The {@link Trie} can also
+ * The {@link org.apache.commons.collections4.Trie} can return operations in
+ * lexicographical order using the 'prefixMap', 'submap', or 'iterator' methods.
+ * The {@link org.apache.commons.collections4.Trie} can also
  * scan for items that are 'bitwise' (using an XOR metric) by the 'select' method.
  * Bitwise closeness is determined by the {@link KeyAnalyzer} returning true or
  * false for a bit being set or not in a given key.
  * 
      
- * This PATRICIA {@link Trie} supports both variable length & fixed length
- * keys. Some methods, such as {@link #prefixMap(Object)} are suited only
- * to variable length keys.
+ * This PATRICIA {@link org.apache.commons.collections4.Trie} supports both variable
+ * length & fixed length keys. Some methods, such as {@link #prefixMap(Object)}
+ * are suited only to variable length keys.
  *
  * @see Radix Tree
  * @see PATRICIA