[COLLECTIONS-732] Document that MultiValuedMap.mapIterator() does not support setValue()

src/changes/changes.xml

@@ -29,6 +29,7 @@
     <action type="fix" dev="ggregory" due-to="Naveed Khan, Gary Gregory">Update the index on remove via IndexedCollection.iterator() (#724).</action>
     <action type="fix" dev="ggregory" due-to="thomaslantern, Gary Gregory">[Javadoc] Fix grammar in ArrayStack class Javadoc (#725).</action>
     <action type="fix" dev="ggregory" due-to="Gary Gregory">General Javadoc improvements.</action>
+    <action type="fix" dev="ggregory" due-to="Chen, Sharang Gupta" issue="COLLECTIONS-732">[Javadoc] Document that MultiValuedMap.mapIterator() does not support MapIterator.setValue(Object).</action>
     <action type="fix" dev="ggregory" due-to="Naveed Khan, Gary Gregory">Fix AbstractLinkedList addAll returning true for an empty collection (#726).</action>
     <action type="fix" dev="ggregory" due-to="Thomas Mortagne, Gary Gregory" issue="COLLECTIONS-898">AbstractSetTest cannot be used with an explicitly typed Set (unless it's based on String) (#727).</action>
     <action type="fix" dev="ggregory" due-to="Naveed Khan, Gary Gregory">Fix map and bidimap nextKey() skipping a key and throwing for keys not in the map (#728).</action>

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

@@ -181,6 +181,11 @@ default MultiValuedMap<V, K> inverted() {
      * <p>
      * A map iterator is an efficient way of iterating over maps. There is no need to access the entries collection or use {@code Map.Entry} objects.
      * </p>
+     * <p>
+     * The iterator visits one key-value mapping at a time, so a key with several values is returned once per value. The implementations in this
+     * library do not support {@link MapIterator#setValue(Object)} and throw an {@link UnsupportedOperationException} from it; to replace a value,
+     * remove the mapping, with {@link MapIterator#remove()} or {@link #removeMapping(Object, Object)}, and {@link #put(Object, Object) put} the new one.
+     * </p>
      *
      * @return A map iterator.
      */

src/main/java/org/apache/commons/collections4/multimap/AbstractMultiValuedMap.java

@@ -344,6 +344,14 @@ public void remove() {
             it.remove();
         }
 
+        /**
+         * Always throws {@link UnsupportedOperationException}, as the entries of a multivalued map are read-only.
+         *
+         * @param value Ignored.
+         * @return Never returns normally.
+         * @throws IllegalStateException if {@link #next()} has not been called yet.
+         * @throws UnsupportedOperationException Always thrown otherwise.
+         */
         @Override
         public V setValue(final V value) {
             if (current == null) {
@@ -747,6 +755,13 @@ public Set<K> keySet() {
         return getMap().keySet();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * The returned iterator does not support {@link MapIterator#setValue(Object)}: the entries it iterates are read-only, so {@code setValue}
+     * throws an {@link UnsupportedOperationException}.
+     * </p>
+     */
     @Override
     public MapIterator<K, V> mapIterator() {
         if (isEmpty()) {