Map default methods in JDK 8 have poor Javadoc

The Javadoc for the new default methods in Map are poor. A Javadoc description should start with the positive, not the negative. I had to read the code to figure out what they are supposed to do. Here are the four poor Javadocs and some proposed enhancements:


merge()
"If the specified key is not already associated with ..."
should be:
"Updates the value for an existing key merging the existing value with the specified value."
"<p>"
"....more detailed user-level explanation..."
"<p>"
"....now the more spec/edge case part..."
("if" is a terrible way to start the docs. Say what it does!)


computeIfAbsent()
"If the specified key is not already associated with a value (or is mapped..."
should be:
"Associates the key with a value computed on demand if the key is not currently present."
"<p>"
"....more detailed user-level explanation..."
"<p>"
"....now the more spec/edge case part..."


computeIfPresent()
"If the value for the specified key is present and non-null,"
should be
"Updates the value for an existing key."
"<p>"
"....more detailed user-level explanation..."
"<p>"
"....now the more spec/edge case part..."


compute()
"Attempts to compute a mapping for the specified key..."
should be
"Updates the value for a key, adding a new mapping if necessary."
"<p>"
"....more detailed user-level explanation..."
"<p>"
"....now the more spec/edge case part..."
(attempts is negative, not positive)


Similar problems seem to exist for "putIfAbsent".


In addition, the example code should use HashSet::new according to lambda best practice.

Not fixing this before JDK 8 will result in these methods receiving a lot less use than they should as developers will struggle to work out what they do.

See core-libs-dev
http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-November/023556.html