Javadocs for mutablePrimitiveObjectMaps.

Signed-off-by: John Dimeo <dimeo@elderresearch.com>

eclipse-collections-code-generator/src/main/resources/api/map/mutablePrimitiveObjectMap.stg

@@ -31,6 +31,14 @@ import org.eclipse.collections.api.tuple.primitive.<name>ObjectPair;
  */
 public interface Mutable<name>ObjectMap\<V> extends <name>ObjectMap\<V>, MutablePrimitiveObjectMap\<V>
 {
+    /**
+     * Associates a value with the specified key. If a value is already associated
+     * with the key in this map, it will be replaced with {@code value}.
+     * @param key the key
+     * @param value the value to associate with {@code value}
+     * @return the value previously associated with {@code key} if one existed, or
+     * {@code null} if not
+     */
     V put(<type> key, V value);
 
     /**
@@ -45,20 +53,71 @@ public interface Mutable<name>ObjectMap\<V> extends <name>ObjectMap\<V>, Mutable
     }
 
     /**
+     * Puts all of the key/value mappings from the specified map into this map. If this
+     * map already has a value associated with one of the keys in the map, it will be
+     * replaced with the value in {@code map}.
+     * @param map the map to copy into this map
      * @since 5.0.
      */
     void putAll(<name>ObjectMap\<? extends V> map);
 
+    /**
+     * Removes the mapping associated with the key, if one exists, from the map.
+     * @param key the key to remove
+     * @see #remove(<type>)
+     */
     V removeKey(<type> key);
 
+    /**
+     * Removes the mapping associated with the key, if one exists, from the map.
+     * @param key the key to remove
+     * @see #removeKey(<type>)
+     */
     V remove(<type> key);
 
+    /**
+     * Retrieves the value associated with the key if one exists; if it does not,
+     * associates a value with the key.
+     * a new value with they key
+     * @param key the key
+     * @param value the value to associate with {@code key} if no such mapping exists
+     * @return the value associated with key, if one exists, or {@code value} if not
+     */
     V getIfAbsentPut(<type> key, V value);
 
+    /**
+     * Retrieves the value associated with the key if one exists; if it does not,
+     * associates the result of invoking the value supplier with the key.
+     * @param key the key
+     * @param function the supplier that provides the value if no mapping exists for {@code key}
+     * @return the value associated with the key, if one exists, or the result of
+     * invoking {@code function} if not
+     */
     V getIfAbsentPut(<type> key, Function0\<? extends V> function);
 
+    /**
+     * Retrieves the value associated with the key if one exists; if it does not,
+     * associates the result of invoking the value function with the key.
+     * @param key the key
+     * @param function the function that provides the value if no mapping exists.
+     * The {@code key} will be passed as the argument to the function.
+     * @return the value associated with the key, if one exists, or the result of
+     * invoking {@code function} with {@code key} if not
+     */
     V getIfAbsentPutWithKey(<type> key, <name>ToObjectFunction\<? extends V> function);
 
+    /**
+     * Retrieves the value associated with the key if one exists; if it does not,
+     * associates the result of invoking the value function with the key.
+     * @param key the key
+     * @param function the function that provides the value if no mapping exists.
+     * The specified {@code parameter} will be passed as the argument to the function.
+     * @param parameter the parameter to provide to {@code function} if no value
+     * exists for {@code key}
+     * @param \<P> the type of the value function's {@code parameter}
+     * @return the value associated with the key, if one exists, or the result of
+     * invoking {@code function} with {@code parameter} if not
+     */
     \<P> V getIfAbsentPutWith(<type> key, Function\<? super P, ? extends V> function, P parameter);
 
     /**
@@ -68,8 +127,21 @@ public interface Mutable<name>ObjectMap\<V> extends <name>ObjectMap\<V>, Mutable
     V updateValue(<type> key, Function0\<? extends V> factory, Function\<? super V, ? extends V> function);
 
     /**
-     * Same as {@link #updateValue(<type>, Function0, Function)} with a Function2 and specified parameter which is
-     * passed to the function.
+     * Updates or sets the value associated with the key by applying the function to the
+     * existing value, if one exists, or the initial value supplied by the factory if one does not.
+     * @param key the key
+     * @param factory the supplier providing the initial value to the function if no
+     * mapping exists for the key
+     * @param function the function that returns the updated value based on the current
+     * value or the initial value, if no value exists. The specified {@code parameter}
+     * will also be passed as the second argument to the function.
+     * @param parameter the parameter to provide to {@code function} if no value
+     * exists for {@code key}
+     * @param \<P> the type of the value function's {@code parameter}
+     * @return the new value associated with the key, either as a result of applying
+     * {@code function} to the value already associated with the key or as a result of
+     * applying it to the value returned by {@code factory} and associating the result
+     * with {@code key}
      */
     \<P> V updateValueWith(<type> key, Function0\<? extends V> factory, Function2\<? super V, ? super P, ? extends V> function, P parameter);
 
@@ -85,12 +157,40 @@ public interface Mutable<name>ObjectMap\<V> extends <name>ObjectMap\<V>, Mutable
     @Override
     Mutable<name>ObjectMap\<V> reject(<name>ObjectPredicate\<? super V> predicate);
 
+    /**
+     * Associates a value with the specified key. If a value is already associated
+     * with the key in this map, it will be replaced with {@code value}.
+     * @param key the key
+     * @param value the value to associate with {@code value}
+     * @return this map
+     * @see #put(<type>, V)
+     */
     Mutable<name>ObjectMap\<V> withKeyValue(<type> key, V value);
 
+    /**
+     * Removes the mapping associated with the key, if one exists, from this map.
+     * @param key the key to remove
+     * @return this map
+     * @see #remove(<type>)
+     */
     Mutable<name>ObjectMap\<V> withoutKey(<type> key);
 
+    /**
+     * Removes the mappings associated with all the keys, if they exist, from this map.
+     * @param keys the keys to remove
+     * @return this map
+     * @see #remove(<type>)
+     */
     Mutable<name>ObjectMap\<V> withoutAllKeys(<name>Iterable keys);
 
+    /**
+     * Puts all of the key/value mappings from the specified pairs into this map. If this
+     * map already has a value associated with one of the keys in the pairs, it will be
+     * replaced with the value in the pair.
+     * @param iterable the pairs to put into this map
+     * @return this map
+     * @see #putPair(<name>ObjectPair)
+     */
     default Mutable<name>ObjectMap\<V> withAllKeyValues(Iterable\<<name>ObjectPair\<V>\> keyValuePairs)
     {
         for (<name>ObjectPair\<V> keyValuePair : keyValuePairs)
@@ -100,8 +200,20 @@ public interface Mutable<name>ObjectMap\<V> extends <name>ObjectMap\<V>, Mutable
         return this;
     }
 
+    /**
+     * Returns an unmodifiable view of this map, delegating all read-only operations to this
+     * map and throwing an {@link UnsupportedOperationException} for all mutating operations.
+     * This avoids the overhead of copying the map when calling {@link #toImmutable()} while
+     * still providing immutability.
+     * @return an unmodifiable view of this map
+     */
     Mutable<name>ObjectMap\<V> asUnmodifiable();
 
+    /**
+     * Returns a synchronized view of this map, delegating all operations to this map but
+     * ensuring only one caller has access to the map at a time.
+     * @return a synchronized view of this map
+     */
     Mutable<name>ObjectMap\<V> asSynchronized();
 }