Document some unchecked casts

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

src/main/java/org/apache/commons/collections/BagUtils.java

@@ -230,7 +230,7 @@ public class BagUtils {
      * @param <E> the element type
      * @return an empty Bag
      */
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
     public static <E> Bag<E> emptyBag() {
         return (Bag<E>) EMPTY_BAG;        
     }
@@ -241,7 +241,7 @@ public class BagUtils {
      * @param <E> the element type
      * @return an empty sorted Bag
      */
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
     public static <E> SortedBag<E> emptySortedBag() {
         return (SortedBag<E>) EMPTY_SORTED_BAG;        
     }

src/main/java/org/apache/commons/collections/BufferUtils.java

@@ -198,7 +198,7 @@ public class BufferUtils {
      * @param <E> the type of the elements in the buffer
      * @return an empty {@link Buffer}
      */
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings("unchecked") // OK, empty buffer is compatible with any type
     public static <E> Buffer<E> emptyBuffer() {
         return (Buffer<E>) EMPTY_BUFFER;
     }

src/main/java/org/apache/commons/collections/IteratorUtils.java

@@ -846,7 +846,6 @@ public class IteratorUtils {
      * @throws NullPointerException if arrayClass is null
      * @throws ClassCastException if the arrayClass is invalid
      */
-    @SuppressWarnings("unchecked")
     public static <E> E[] toArray(final Iterator<? extends E> iterator, final Class<E> arrayClass) {
         if (iterator == null) {
             throw new NullPointerException("Iterator must not be null");
@@ -855,7 +854,9 @@ public class IteratorUtils {
             throw new NullPointerException("Array class must not be null");
         }
         final List<E> list = toList(iterator, 100);
-        return list.toArray((E[]) Array.newInstance(arrayClass, list.size()));
+        @SuppressWarnings("unchecked") // as per Javadoc, will throw CCE if class is wrong
+        final E[] array = (E[]) Array.newInstance(arrayClass, list.size());
+        return list.toArray(array);
     }
 
     /**

src/main/java/org/apache/commons/collections/MapUtils.java

@@ -1129,7 +1129,7 @@ public class MapUtils {
      * @throws ClassCastException if the array contents is mixed
      * @since 3.2
      */
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings("unchecked") // As per Javadoc throws CCE for invalid array contents
     public static <K, V> Map<K, V> putAll(final Map<K, V> map, final Object[] array) {
         map.size();  // force NPE
         if (array == null || array.length == 0) {
@@ -1138,11 +1138,13 @@ public class MapUtils {
         final Object obj = array[0];
         if (obj instanceof Map.Entry) {
             for (final Object element : array) {
+                // cast ok here, type is checked above
                 final Map.Entry<K, V> entry = (Map.Entry<K, V>) element;
                 map.put(entry.getKey(), entry.getValue());
             }
         } else if (obj instanceof KeyValue) {
             for (final Object element : array) {
+                // cast ok here, type is checked above
                 final KeyValue<K, V> keyval = (KeyValue<K, V>) element;
                 map.put(keyval.getKey(), keyval.getValue());
             }
@@ -1152,10 +1154,12 @@ public class MapUtils {
                 if (sub == null || sub.length < 2) {
                     throw new IllegalArgumentException("Invalid array element: " + i);
                 }
+                // these casts can fail if array has incorrect types
                 map.put((K) sub[0], (V) sub[1]);
             }
         } else {
             for (int i = 0; i < array.length - 1;) {
+                // these casts can fail if array has incorrect types
                 map.put((K) array[i++], (V) array[i++]);
             }
         }

src/main/java/org/apache/commons/collections/SetUtils.java

@@ -69,7 +69,7 @@ public class SetUtils {
      * @param <E> the element type
      * @return an empty sorted Set
      */
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings("unchecked") // empty set is OK for any type
     public static <E> SortedSet<E> emptySortedSet() {
         return (SortedSet<E>) EMPTY_SORTED_SET;
     }