From 161ea257226ac3ae4b1cb9e80279de9ff885cf8b Mon Sep 17 00:00:00 2001
From: Thomas Neidhart <tn@apache.org>
Date: Fri, 7 Sep 2012 20:53:09 +0000
Subject: [PATCH] Javadoc fixes.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1382169 13f79535-47bb-0310-9956-ffa450edef68
---
 .../commons/collections/map/CompositeMap.java |  1 +
 .../commons/collections/map/DefaultedMap.java |  6 ++++
 .../commons/collections/map/FixedSizeMap.java |  2 ++
 .../collections/map/FixedSizeSortedMap.java   |  2 ++
 .../commons/collections/map/LRUMap.java       |  1 +
 .../commons/collections/map/LazyMap.java      |  4 +++
 .../collections/map/LazySortedMap.java        |  6 ++++
 .../collections/map/ListOrderedMap.java       |  4 +++
 .../commons/collections/map/MultiKeyMap.java  | 30 ++++++++++++------
 .../collections/map/MultiValueMap.java        |  9 ++++++
 .../collections/map/PassiveExpiringMap.java   | 31 ++++++++++---------
 .../collections/map/PredicatedMap.java        |  4 +++
 .../collections/map/PredicatedSortedMap.java  |  3 ++
 .../collections/map/TransformedMap.java       | 12 +++++--
 .../collections/map/TransformedSortedMap.java |  9 ++++--
 .../collections/map/UnmodifiableEntrySet.java |  3 ++
 .../collections/map/UnmodifiableMap.java      |  3 ++
 .../map/UnmodifiableOrderedMap.java           |  3 ++
 .../map/UnmodifiableSortedMap.java            |  3 ++
 19 files changed, 108 insertions(+), 28 deletions(-)

diff --git a/src/main/java/org/apache/commons/collections/map/CompositeMap.java b/src/main/java/org/apache/commons/collections/map/CompositeMap.java
index 357504199..d09864066 100644
--- a/src/main/java/org/apache/commons/collections/map/CompositeMap.java
+++ b/src/main/java/org/apache/commons/collections/map/CompositeMap.java
@@ -472,6 +472,7 @@ public class CompositeMap<K, V> extends AbstractIterableMap<K, V> implements Ser
 
     /**
      * Gets a hash code for the Map as per the Map specification.
+     * {@inheritDoc}
      */
     @Override
     public int hashCode() {
diff --git a/src/main/java/org/apache/commons/collections/map/DefaultedMap.java b/src/main/java/org/apache/commons/collections/map/DefaultedMap.java
index bf5907c00..d9b62c8d4 100644
--- a/src/main/java/org/apache/commons/collections/map/DefaultedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/DefaultedMap.java
@@ -75,6 +75,8 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
      * <p>
      * The value specified is returned when a missing key is found.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param defaultValue  the default value to return when the key is not found
      * @return a new defaulting map
@@ -90,6 +92,8 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
      * The factory specified is called when a missing key is found.
      * The result will be returned as the result of the map get(key) method.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param factory  the factory to use to create entries, must not be null
      * @return a new defaulting map
@@ -109,6 +113,8 @@ public class DefaultedMap<K, V> extends AbstractMapDecorator<K, V> implements Se
      * The key is passed to the transformer as the input, and the result
      * will be returned as the result of the map get(key) method.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param transformer  the transformer to use as a factory to create entries, must not be null
      * @return a new defaulting map
diff --git a/src/main/java/org/apache/commons/collections/map/FixedSizeMap.java b/src/main/java/org/apache/commons/collections/map/FixedSizeMap.java
index 3627af871..9b6d39001 100644
--- a/src/main/java/org/apache/commons/collections/map/FixedSizeMap.java
+++ b/src/main/java/org/apache/commons/collections/map/FixedSizeMap.java
@@ -62,6 +62,8 @@ public class FixedSizeMap<K, V>
     /**
      * Factory method to create a fixed size map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @return a new fixed size map
      * @throws IllegalArgumentException if map is null
diff --git a/src/main/java/org/apache/commons/collections/map/FixedSizeSortedMap.java b/src/main/java/org/apache/commons/collections/map/FixedSizeSortedMap.java
index cf6e24bf7..6adf92be9 100644
--- a/src/main/java/org/apache/commons/collections/map/FixedSizeSortedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/FixedSizeSortedMap.java
@@ -64,6 +64,8 @@ public class FixedSizeSortedMap<K, V>
     /**
      * Factory method to create a fixed size sorted map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @return a new fixed size sorted map
      * @throws IllegalArgumentException if map is null
diff --git a/src/main/java/org/apache/commons/collections/map/LRUMap.java b/src/main/java/org/apache/commons/collections/map/LRUMap.java
index 086de2c9f..65696554c 100644
--- a/src/main/java/org/apache/commons/collections/map/LRUMap.java
+++ b/src/main/java/org/apache/commons/collections/map/LRUMap.java
@@ -360,6 +360,7 @@ public class LRUMap<K, V>
      * This is fixed in version 3.1 onwards.
      *
      * @param entry  the entry to be removed
+     * @return {@code true}
      */
     protected boolean removeLRU(LinkEntry<K, V> entry) {
         return true;
diff --git a/src/main/java/org/apache/commons/collections/map/LazyMap.java b/src/main/java/org/apache/commons/collections/map/LazyMap.java
index 8bb2a1b7c..f575f8163 100644
--- a/src/main/java/org/apache/commons/collections/map/LazyMap.java
+++ b/src/main/java/org/apache/commons/collections/map/LazyMap.java
@@ -70,6 +70,8 @@ public class LazyMap<K, V> extends AbstractMapDecorator<K, V> implements Map<K,
     /**
      * Factory method to create a lazily instantiated map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param factory  the factory to use, must not be null
      * @return a new lazy map
@@ -82,6 +84,8 @@ public class LazyMap<K, V> extends AbstractMapDecorator<K, V> implements Map<K,
     /**
      * Factory method to create a lazily instantiated map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param factory  the factory to use, must not be null
      * @return a new lazy map
diff --git a/src/main/java/org/apache/commons/collections/map/LazySortedMap.java b/src/main/java/org/apache/commons/collections/map/LazySortedMap.java
index c0f308c69..9f45dfd1a 100644
--- a/src/main/java/org/apache/commons/collections/map/LazySortedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/LazySortedMap.java
@@ -66,8 +66,11 @@ public class LazySortedMap<K,V>
     /**
      * Factory method to create a lazily instantiated sorted map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param factory  the factory to use, must not be null
+     * @return a new lazy sorted map
      * @throws IllegalArgumentException if map or factory is null
      */
     public static <K, V> LazySortedMap<K, V> lazySortedMap(SortedMap<K, V> map, Factory<? extends V> factory) {
@@ -77,8 +80,11 @@ public class LazySortedMap<K,V>
     /**
      * Factory method to create a lazily instantiated sorted map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param factory  the factory to use, must not be null
+     * @return a new lazy sorted map
      * @throws IllegalArgumentException if map or factory is null
      */
     public static <K, V> LazySortedMap<K, V> lazySortedMap(SortedMap<K, V> map,
diff --git a/src/main/java/org/apache/commons/collections/map/ListOrderedMap.java b/src/main/java/org/apache/commons/collections/map/ListOrderedMap.java
index 4d6facb6d..135644671 100644
--- a/src/main/java/org/apache/commons/collections/map/ListOrderedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/ListOrderedMap.java
@@ -89,7 +89,10 @@ public class ListOrderedMap<K, V>
      * <p>
      * An <code>ArrayList</code> is used to retain order.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
+     * @return a new list ordered map
      * @throws IllegalArgumentException if map is null
      */
     public static <K, V> ListOrderedMap<K, V> listOrderedMap(Map<K, V> map) {
@@ -402,6 +405,7 @@ public class ListOrderedMap<K, V>
      * Sets the value at the specified index.
      *
      * @param index  the index of the value to set
+     * @param value  the new value to set
      * @return the previous value at that index
      * @throws IndexOutOfBoundsException if the index is invalid
      * @since 3.2
diff --git a/src/main/java/org/apache/commons/collections/map/MultiKeyMap.java b/src/main/java/org/apache/commons/collections/map/MultiKeyMap.java
index 98bb3fd2b..a512c8774 100644
--- a/src/main/java/org/apache/commons/collections/map/MultiKeyMap.java
+++ b/src/main/java/org/apache/commons/collections/map/MultiKeyMap.java
@@ -87,7 +87,10 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      * Decorates the specified map to add the MultiKeyMap API and fast query.
      * The map must not be null and must be empty.
      *
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, not null
+     * @return a new multi key map
      * @throws IllegalArgumentException if the map is null or not empty
      */
     public static <K, V> MultiKeyMap<K, V> multiKeyMap(AbstractHashedMap<MultiKey<? extends K>, V> map) {
@@ -151,7 +154,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      */
     public boolean containsKey(Object key1, Object key2) {
         int hashCode = hash(key1, key2);
-        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry = decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
+        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry =
+                decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
         while (entry != null) {
             if (entry.hashCode == hashCode && isEqualKey(entry, key1, key2)) {
                 return true;
@@ -259,7 +263,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      */
     public V get(Object key1, Object key2, Object key3) {
         int hashCode = hash(key1, key2, key3);
-        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry = decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
+        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry =
+                decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
         while (entry != null) {
             if (entry.hashCode == hashCode && isEqualKey(entry, key1, key2, key3)) {
                 return entry.getValue();
@@ -279,7 +284,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      */
     public boolean containsKey(Object key1, Object key2, Object key3) {
         int hashCode = hash(key1, key2, key3);
-        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry = decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
+        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry =
+                decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
         while (entry != null) {
             if (entry.hashCode == hashCode && isEqualKey(entry, key1, key2, key3)) {
                 return true;
@@ -374,7 +380,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      * @param key3  the third key
      * @return true if the key matches
      */
-    protected boolean isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry, Object key1, Object key2, Object key3) {
+    protected boolean isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry,
+                                 Object key1, Object key2, Object key3) {
         MultiKey<? extends K> multi = entry.getKey();
         return
             multi.size() == 3 &&
@@ -395,7 +402,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      */
     public V get(Object key1, Object key2, Object key3, Object key4) {
         int hashCode = hash(key1, key2, key3, key4);
-        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry = decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
+        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry =
+                decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
         while (entry != null) {
             if (entry.hashCode == hashCode && isEqualKey(entry, key1, key2, key3, key4)) {
                 return entry.getValue();
@@ -416,7 +424,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      */
     public boolean containsKey(Object key1, Object key2, Object key3, Object key4) {
         int hashCode = hash(key1, key2, key3, key4);
-        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry = decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
+        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry =
+                decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
         while (entry != null) {
             if (entry.hashCode == hashCode && isEqualKey(entry, key1, key2, key3, key4)) {
                 return true;
@@ -518,7 +527,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      * @param key4  the fourth key
      * @return true if the key matches
      */
-    protected boolean isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry, Object key1, Object key2, Object key3, Object key4) {
+    protected boolean isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry,
+                                 Object key1, Object key2, Object key3, Object key4) {
         MultiKey<? extends K> multi = entry.getKey();
         return
             multi.size() == 4 &&
@@ -541,7 +551,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      */
     public V get(Object key1, Object key2, Object key3, Object key4, Object key5) {
         int hashCode = hash(key1, key2, key3, key4, key5);
-        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry = decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
+        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry =
+                decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
         while (entry != null) {
             if (entry.hashCode == hashCode && isEqualKey(entry, key1, key2, key3, key4, key5)) {
                 return entry.getValue();
@@ -563,7 +574,8 @@ public class MultiKeyMap<K, V> extends AbstractMapDecorator<MultiKey<? extends K
      */
     public boolean containsKey(Object key1, Object key2, Object key3, Object key4, Object key5) {
         int hashCode = hash(key1, key2, key3, key4, key5);
-        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry = decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
+        AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry =
+                decorated().data[decorated().hashIndex(hashCode, decorated().data.length)];
         while (entry != null) {
             if (entry.hashCode == hashCode && isEqualKey(entry, key1, key2, key3, key4, key5)) {
                 return true;
diff --git a/src/main/java/org/apache/commons/collections/map/MultiValueMap.java b/src/main/java/org/apache/commons/collections/map/MultiValueMap.java
index 1532cb14b..ffb7166ae 100644
--- a/src/main/java/org/apache/commons/collections/map/MultiValueMap.java
+++ b/src/main/java/org/apache/commons/collections/map/MultiValueMap.java
@@ -74,7 +74,10 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
      * Creates a map which wraps the given map and
      * maps keys to ArrayLists.
      *
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to wrap
+     * @return a new multi-value map
      */
     @SuppressWarnings({ "unchecked", "rawtypes" })
     public static <K, V> MultiValueMap<K, V> multiValueMap(Map<K, ? super Collection<V>> map) {
@@ -85,8 +88,11 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
      * Creates a map which decorates the given <code>map</code> and
      * maps keys to collections of type <code>collectionClass</code>.
      *
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to wrap
      * @param collectionClass  the type of the collection class
+     * @return a new multi-value map
      */
     public static <K, V, C extends Collection<V>> MultiValueMap<K, V> multiValueMap(Map<K, ? super C> map,
                                                                                     Class<C> collectionClass) {
@@ -97,8 +103,11 @@ public class MultiValueMap<K, V> extends AbstractMapDecorator<K, Object> impleme
      * Creates a map which decorates the given <code>map</code> and
      * creates the value collections using the supplied <code>collectionFactory</code>.
      *
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate
      * @param collectionFactory  the collection factory (must return a Collection object).
+     * @return a new multi-value map
      */
     public static <K, V, C extends Collection<V>> MultiValueMap<K, V> multiValueMap(Map<K, ? super C> map,
                                                                                     Factory<C> collectionFactory) {
diff --git a/src/main/java/org/apache/commons/collections/map/PassiveExpiringMap.java b/src/main/java/org/apache/commons/collections/map/PassiveExpiringMap.java
index 0be932380..5aa2ca3a6 100644
--- a/src/main/java/org/apache/commons/collections/map/PassiveExpiringMap.java
+++ b/src/main/java/org/apache/commons/collections/map/PassiveExpiringMap.java
@@ -339,6 +339,7 @@ public class PassiveExpiringMap<K, V>
     /**
      * All expired entries are removed from the map prior to determining the
      * contains result.
+     * {@inheritDoc}
      */
     @Override
     public boolean containsKey(Object key) {
@@ -349,6 +350,7 @@ public class PassiveExpiringMap<K, V>
     /**
      * All expired entries are removed from the map prior to determining the
      * contains result.
+     * {@inheritDoc}
      */
     @Override
     public boolean containsValue(Object value) {
@@ -357,8 +359,8 @@ public class PassiveExpiringMap<K, V>
     }
 
     /**
-     * All expired entries are removed from the map prior to returning the entry
-     * set.
+     * All expired entries are removed from the map prior to returning the entry set.
+     * {@inheritDoc}
      */
     @Override
     public Set<Entry<K, V>> entrySet() {
@@ -367,8 +369,8 @@ public class PassiveExpiringMap<K, V>
     }
 
     /**
-     * All expired entries are removed from the map prior to returning the entry
-     * value.
+     * All expired entries are removed from the map prior to returning the entry value.
+     * {@inheritDoc}
      */
     @Override
     public V get(Object key) {
@@ -377,8 +379,8 @@ public class PassiveExpiringMap<K, V>
     }
 
     /**
-     * All expired entries are removed from the map prior to determining if it
-     * is empty.
+     * All expired entries are removed from the map prior to determining if it is empty.
+     * {@inheritDoc}
      */
     @Override
     public boolean isEmpty() {
@@ -387,7 +389,7 @@ public class PassiveExpiringMap<K, V>
     }
 
     /**
-     * Determines if the given expiration time is less than <code>now</code>
+     * Determines if the given expiration time is less than <code>now</code>.
      * 
      * @param now the time in milliseconds used to compare against the
      *        expiration time.
@@ -406,8 +408,8 @@ public class PassiveExpiringMap<K, V>
     }
 
     /**
-     * All expired entries are removed from the map prior to returning the key
-     * set.
+     * All expired entries are removed from the map prior to returning the key set.
+     * {@inheritDoc}
      */
     @Override
     public Set<K> keySet() {
@@ -428,9 +430,8 @@ public class PassiveExpiringMap<K, V>
     }
 
     /**
-     * Add the given key-value pair to this map as well as recording the entry's
-     * expiration time based on the current time in milliseconds,
-     * <code>now</code> and this map's {@link #expiringPolicy}.
+     * Add the given key-value pair to this map as well as recording the entry's expiration time based on
+     * the current time in milliseconds, <code>now</code> and this map's {@link #expiringPolicy}.
      */
     private V put(K key, V value, long now) {
         // record expiration time of new entry
@@ -450,6 +451,7 @@ public class PassiveExpiringMap<K, V>
     /**
      * Normal {@link Map#remove(Object)} behavior with the addition of removing
      * any expiration entry as well.
+     * {@inheritDoc}
      */
     @Override
     public V remove(Object key) {
@@ -492,6 +494,7 @@ public class PassiveExpiringMap<K, V>
 
     /**
      * All expired entries are removed from the map prior to returning the size.
+     * {@inheritDoc}
      */
     @Override
     public int size() {
@@ -527,8 +530,8 @@ public class PassiveExpiringMap<K, V>
     }
 
     /**
-     * All expired entries are removed from the map prior to returning the value
-     * collection.
+     * All expired entries are removed from the map prior to returning the value collection.
+     * {@inheritDoc}
      */
     @Override
     public Collection<V> values() {
diff --git a/src/main/java/org/apache/commons/collections/map/PredicatedMap.java b/src/main/java/org/apache/commons/collections/map/PredicatedMap.java
index 21f5d3924..0554eabe1 100644
--- a/src/main/java/org/apache/commons/collections/map/PredicatedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/PredicatedMap.java
@@ -66,9 +66,12 @@ public class PredicatedMap<K, V>
      * If there are any elements already in the list being decorated, they
      * are validated.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param keyPredicate  the predicate to validate the keys, null means no check
      * @param valuePredicate  the predicate to validate to values, null means no check
+     * @return a new predicated map
      * @throws IllegalArgumentException if the map is null
      */
     public static <K, V> PredicatedMap<K, V> predicatedMap(Map<K, V> map,
@@ -146,6 +149,7 @@ public class PredicatedMap<K, V>
      * Override to validate an object set into the map via <code>setValue</code>.
      * 
      * @param value  the value to validate
+     * @return the value itself
      * @throws IllegalArgumentException if invalid
      * @since 3.1
      */
diff --git a/src/main/java/org/apache/commons/collections/map/PredicatedSortedMap.java b/src/main/java/org/apache/commons/collections/map/PredicatedSortedMap.java
index 17242d2af..519545fcf 100644
--- a/src/main/java/org/apache/commons/collections/map/PredicatedSortedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/PredicatedSortedMap.java
@@ -54,9 +54,12 @@ public class PredicatedSortedMap<K, V> extends PredicatedMap<K, V> implements So
      * If there are any elements already in the list being decorated, they
      * are validated.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param keyPredicate  the predicate to validate the keys, null means no check
      * @param valuePredicate  the predicate to validate to values, null means no check
+     * @return a new predicated sorted map
      * @throws IllegalArgumentException if the map is null
      */
     public static <K, V> PredicatedSortedMap<K, V> predicatedSortedMap(SortedMap<K, V> map,
diff --git a/src/main/java/org/apache/commons/collections/map/TransformedMap.java b/src/main/java/org/apache/commons/collections/map/TransformedMap.java
index d63ed3d2f..a61310769 100644
--- a/src/main/java/org/apache/commons/collections/map/TransformedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/TransformedMap.java
@@ -64,9 +64,12 @@ public class TransformedMap<K, V>
      * are NOT transformed.
      * Contrast this with {@link #transformedMap(Map, Transformer, Transformer)}.
      *
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param keyTransformer  the transformer to use for key conversion, null means no transformation
      * @param valueTransformer  the transformer to use for value conversion, null means no transformation
+     * @return a new transformed map
      * @throws IllegalArgumentException if map is null
      */
     public static <K, V> TransformedMap<K, V> transformingMap(Map<K, V> map,
@@ -83,9 +86,12 @@ public class TransformedMap<K, V>
      * will be transformed by this method.
      * Contrast this with {@link #transformingMap(Map, Transformer, Transformer)}.
      *
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param keyTransformer  the transformer to use for key conversion, null means no transformation
      * @param valueTransformer  the transformer to use for value conversion, null means no transformation
+     * @return a new transformed map
      * @throws IllegalArgumentException if map is null
      * @since 3.2
      */
@@ -154,7 +160,7 @@ public class TransformedMap<K, V>
      * The transformer itself may throw an exception if necessary.
      *
      * @param object  the object to transform
-     * @throws the transformed object
+     * @return the transformed object
      */
     protected K transformKey(K object) {
         if (keyTransformer == null) {
@@ -169,7 +175,7 @@ public class TransformedMap<K, V>
      * The transformer itself may throw an exception if necessary.
      *
      * @param object  the object to transform
-     * @throws the transformed object
+     * @return the transformed object
      */
     protected V transformValue(V object) {
         if (valueTransformer == null) {
@@ -184,7 +190,7 @@ public class TransformedMap<K, V>
      * The transformer itself may throw an exception if necessary.
      *
      * @param map  the map to transform
-     * @throws the transformed object
+     * @return the transformed object
      */
     @SuppressWarnings("unchecked")
     protected Map<K, V> transformMap(Map<? extends K, ? extends V> map) {
diff --git a/src/main/java/org/apache/commons/collections/map/TransformedSortedMap.java b/src/main/java/org/apache/commons/collections/map/TransformedSortedMap.java
index ac533e828..8ccbe2bef 100644
--- a/src/main/java/org/apache/commons/collections/map/TransformedSortedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/TransformedSortedMap.java
@@ -51,13 +51,15 @@ public class TransformedSortedMap<K, V>
     /**
      * Factory method to create a transforming sorted map.
      * <p>
-     * If there are any elements already in the map being decorated, they
-     * are NOT transformed.
+     * If there are any elements already in the map being decorated, they are NOT transformed.
      * Contrast this with {@link #transformedSortedMap(SortedMap, Transformer, Transformer)}.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param keyTransformer  the predicate to validate the keys, null means no transformation
      * @param valueTransformer  the predicate to validate to values, null means no transformation
+     * @return a new transformed sorted map
      * @throws IllegalArgumentException if the map is null
      */
     public static <K, V> TransformedSortedMap<K, V> transformingSortedMap(SortedMap<K, V> map,
@@ -74,9 +76,12 @@ public class TransformedSortedMap<K, V>
      * will be transformed by this method.
      * Contrast this with {@link #transformingSortedMap(SortedMap, Transformer, Transformer)}.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
      * @param keyTransformer  the transformer to use for key conversion, null means no transformation
      * @param valueTransformer  the transformer to use for value conversion, null means no transformation
+     * @return a new transformed sorted map
      * @throws IllegalArgumentException if map is null
      * @since 3.2
      */
diff --git a/src/main/java/org/apache/commons/collections/map/UnmodifiableEntrySet.java b/src/main/java/org/apache/commons/collections/map/UnmodifiableEntrySet.java
index 9f3b1804c..d190a17a3 100644
--- a/src/main/java/org/apache/commons/collections/map/UnmodifiableEntrySet.java
+++ b/src/main/java/org/apache/commons/collections/map/UnmodifiableEntrySet.java
@@ -44,7 +44,10 @@ public final class UnmodifiableEntrySet<K, V>
     /**
      * Factory method to create an unmodifiable set of Map Entry objects.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param set  the set to decorate, must not be null
+     * @return a new unmodifiable entry set
      * @throws IllegalArgumentException if set is null
      */
     public static <K, V> Set<Map.Entry<K, V>> unmodifiableEntrySet(Set<Map.Entry<K, V>> set) {
diff --git a/src/main/java/org/apache/commons/collections/map/UnmodifiableMap.java b/src/main/java/org/apache/commons/collections/map/UnmodifiableMap.java
index 97a0e0cdb..06c796756 100644
--- a/src/main/java/org/apache/commons/collections/map/UnmodifiableMap.java
+++ b/src/main/java/org/apache/commons/collections/map/UnmodifiableMap.java
@@ -52,7 +52,10 @@ public final class UnmodifiableMap<K, V>
     /**
      * Factory method to create an unmodifiable map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
+     * @return a new unmodifiable map
      * @throws IllegalArgumentException if map is null
      */
     public static <K, V> Map<K, V> unmodifiableMap(Map<K, V> map) {
diff --git a/src/main/java/org/apache/commons/collections/map/UnmodifiableOrderedMap.java b/src/main/java/org/apache/commons/collections/map/UnmodifiableOrderedMap.java
index 46a3c790e..d28bae480 100644
--- a/src/main/java/org/apache/commons/collections/map/UnmodifiableOrderedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/UnmodifiableOrderedMap.java
@@ -50,7 +50,10 @@ public final class UnmodifiableOrderedMap<K, V> extends AbstractOrderedMapDecora
     /**
      * Factory method to create an unmodifiable sorted map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
+     * @return a new ordered map
      * @throws IllegalArgumentException if map is null
      */
     public static <K, V> OrderedMap<K, V> unmodifiableOrderedMap(OrderedMap<K, V> map) {
diff --git a/src/main/java/org/apache/commons/collections/map/UnmodifiableSortedMap.java b/src/main/java/org/apache/commons/collections/map/UnmodifiableSortedMap.java
index 603612339..04344e79e 100644
--- a/src/main/java/org/apache/commons/collections/map/UnmodifiableSortedMap.java
+++ b/src/main/java/org/apache/commons/collections/map/UnmodifiableSortedMap.java
@@ -50,7 +50,10 @@ public final class UnmodifiableSortedMap<K, V>
     /**
      * Factory method to create an unmodifiable sorted map.
      * 
+     * @param <K>  the key type
+     * @param <V>  the value type
      * @param map  the map to decorate, must not be null
+     * @return a new unmodifiable sorted map
      * @throws IllegalArgumentException if map is null
      */
     public static <K, V> SortedMap<K, V> unmodifiableSortedMap(SortedMap<K, V> map) {