TObjectDoubleHashMap.adjustValue() and .adjustOrPutValue() javadocs need clarification

This issue is strictly about javadocs, not functionality / bugs. AFAIK: The code works correctly. I assume these javadocs are generic and copied between classes. My suggestions for improvement can probably be applied to other TObject${? extends Number}Map classes.

Current javadocs for adjustValue():

    /**
     * Adjusts the primitive value mapped to key.
     *
     * @param key the key of the value to increment
     * @param amount the amount to adjust the value by.
     * @return true if a mapping was found and modified.
     */
    public boolean adjustValue( K key, double amount );

I was initially unsure what term "adjust" meant in this context. I needed to look at the code to fully understand.

Suggested javadocs for adjustValue()

    /**
     * Adds an amount to the primitive value mapped to key.  If the key does not exist, the map is not modified (key-value is not inserted).
     *
     * @param key the key of the value to increment
     * @param amount the amount to add to the value; may be positive, zero, or negative
     * @return true if a mapping was found and modified
     * @see #adjustOrPutValue(Object, double, double)
     */
    public boolean adjustValue( K key, double amount );

Current javadocs for adjustOrPutValue():

    /**
     * Adjusts the primitive value mapped to the key if the key is present in the map.
     * Otherwise, the <tt>initial_value</tt> is put in the map.
     *
     * @param key the key of the value to increment
     * @param adjust_amount the amount to adjust the value by
     * @param put_amount the value put into the map if the key is not initial present
     *
     * @return the value present in the map after the adjustment or put operation
     */
    public double adjustOrPutValue( K key, double adjust_amount, double put_amount );

Suggested javadocs for adjustOrPutValue():

    /**
     * Adds an amount to the primitive value mapped to the key if the key is present in the map.
     * Otherwise, the <tt>put_amount</tt> is put in the map.
     *
     * @param key the key of the value to increment
     * @param adjust_amount the amount to add to the value; may be positive, zero, or negative
     * @param put_amount the value put into the map if the key is not present
     *
     * @return the value present in the map after the adjustment or put operation
     */
    public double adjustOrPutValue( K key, double adjust_amount, double put_amount );

Comments (9)