A DESCRIPTION OF THE PROBLEM :
The documenation states 'A hashtable-based Map implementation with weak keys'

This indicates that the WeakHashMap shares synchronization semantics with HashTable. If one reads on in the documentation it clearly states that the WeakHashMap isn't synchronized..

It would be clearer if the documentation stated 'A hashmap-based Map implementation with weak keys'

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
A hashmap-based Map implementation with weak keys
ACTUAL -
A hashtable-based Map implementation with weak keys

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/api/java/util/WeakHashMap.html
(Incident Review ID: 290300) 
======================================================================

N/A

Map is an interface; Hashtable, HashMap and WeakHashMap are independent classes
that implement it.  WeakHashMap is not "based" on HashMap.

A "hash table" is a data structure commonly used in the study of algorithms.
The phrase "A hashtable-based Map implementation with weak keys" is 
referring to this generic term "hash table", not to the class "Hashtable",
and as such is correct.  The way this is written is misleading, however, and
somewhat suggestive of "Hashtable".  

To avoid confusion, perhaps this sentence could be rewritten in the style 
of HashMap ("Hash table based implementation...").  William Safire would
probably argue that "Hash-table-based" is more correct.  Another alternative
would be "Hash-based", which seems to win the popular vote on Google.

  xxxxx@xxxxx   2004-07-30



Here's the proposed patch:


diff --git a/src/share/classes/java/util/Hashtable.java b/src/share/classes/java/util/Hashtable.java
--- a/src/share/classes/java/util/Hashtable.java
+++ b/src/share/classes/java/util/Hashtable.java
@@ -27,7 +27,7 @@ import java.io.*;
 import java.io.*;
 
 /**
- * This class implements a hashtable, which maps keys to values. Any
+ * This class implements a hash table, which maps keys to values. Any
  * non-<code>null</code> object can be used as a key or as a value. <p>
  *
  * To successfully store and retrieve objects from a hashtable, the
diff --git a/src/share/classes/java/util/WeakHashMap.java b/src/share/classes/java/util/WeakHashMap.java
--- a/src/share/classes/java/util/WeakHashMap.java
+++ b/src/share/classes/java/util/WeakHashMap.java
@@ -29,7 +29,8 @@ import java.lang.ref.ReferenceQueue;
 
 
 /**
- * A hashtable-based <tt>Map</tt> implementation with <em>weak keys</em>.
+ * Hash table based implementation of the <tt>Map</tt> interface, with
+ * <em>weak keys</em>.
  * An entry in a <tt>WeakHashMap</tt> will automatically be removed when
  * its key is no longer in ordinary use.  More precisely, the presence of a
  * mapping for a given key will not prevent the key from being discarded by the
Posted Date : 2008-03-06 23:35:03.0