A DESCRIPTION OF THE PROBLEM :
In the "Implementation note:" the last sentence states:
"One way to deal with this is to wrap values themselves within WeakReferences before inserting, as in: m.put(key, new WeakReference(value)), and then unwrapping upon each get."
However, it misleads the user because the value can be GC'd if there are no strong reference to the value. We think a couple more sentences should be added for this scenario.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
One way to deal with this is to wrap values themselves within WeakReferences before inserting, as in: m.put(key, new WeakReference(value)), and then unwrapping upon each get. However, as the use of WeakReference in this manner will not prevent value objects from being GC'd, this approach is only useful when entries in the map are not relied upon for keeping the underlying value objects "live".
ACTUAL -
One way to deal with this is to wrap values themselves within WeakReferences before inserting, as in: m.put(key, new WeakReference(value)), and then unwrapping upon each get.

URL OF FAULTY DOCUMENTATION :
http://docs.oracle.com/javase/7/docs/api/java/util/WeakHashMap.html