[COLLECTIONS-461] Added javadoc clarification to Put. Thanks to mbenson.

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

RELEASE-NOTES.txt

@@ -179,6 +179,8 @@ Changed classes / methods
 Fixed Bugs
 ----------
 
+ o [COLLECTIONS-461] Added additional clarification to javadoc of interface "Put" wrt return type of
+                     "put(Object, Object)" method. Thanks to Matt Benson, sebb. 
  o [COLLECTIONS-447] Tree traversal with a TreeListIterator will not be affected anymore by the removal of an element directly after
                      a call to previous(). Thanks to Jeffrey Barnes. 
  o [COLLECTIONS-445] Adapt and/or ignore several unit tests when run on a IBM J9 VM (specification version 1.6.0) due to a faulty

src/changes/changes.xml

@@ -31,6 +31,10 @@
     <action issue="COLLECTIONS-462" dev="tn" type="add" due-to="Andy Seaborne, Claude Warren">
       Added "PeekingIterator" decorator to support one-element lookahead during iteration.
     </action>
+    <action issue="COLLECTIONS-461" dev="tn" type="fix" due-to="Matt Benson, sebb">
+      Added additional clarification to javadoc of interface "Put" wrt return type of
+      "put(Object, Object)" method. 
+    </action>
     <action issue="COLLECTIONS-460" dev="tn" type="update">
       Changed "IteratorChain" to use internally a "Queue" instead of a "List". Iterators are
       removed from the queue once used and can be garbage collected after being exhausted.

src/main/java/org/apache/commons/collections4/Put.java

@@ -20,6 +20,12 @@ import java.util.Map;
 
 /**
  * The "write" subset of the {@link Map} interface.
+ * <p>
+ * NOTE: in the original {@link Map} interface, {@link Map#put(Object, Object)} is known
+ * to have the same return type as {@link Map#get(Object)}, namely {@code V}. {@link Put}
+ * makes no assumptions in this regard (there is no association with, nor even knowledge
+ * of, a "reading" interface) and thus defines {@link #put(Object, Object)} as returning
+ * {@link Object}.
  *
  * @since 4.0
  * @version $Id$