--- a/src/share/classes/java/util/Hashtable.java Mon Mar 10 23:23:48 2008 -0700
+++ b/src/share/classes/java/util/Hashtable.java Mon Mar 10 23:23:48 2008 -0700
@@ -100,9 +100,15 @@ import java.io.*;
*
* <p>As of the Java 2 platform v1.2, this class was retrofitted to
* implement the {@link Map} interface, making it a member of the
- * <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java
- * Collections Framework</a>. Unlike the new collection
- * implementations, {@code Hashtable} is synchronized.
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
+ *
+ * Java Collections Framework</a>. Unlike the new collection
+ * implementations, {@code Hashtable} is synchronized. If a
+ * thread-safe implementation is not needed, it is recommended to use
+ * {@link HashMap} in place of {@code Hashtable}. If a thread-safe
+ * highly-concurrent implementation is desired, then it is recommended
+ * to use {@link java.util.concurrent.ConcurrentHashMap} in place of
+ * {@code Hashtable}.
*
* @author Arthur van Hoff
* @author Josh Bloch
--- a/src/share/classes/java/util/Vector.java Mon Mar 10 23:23:48 2008 -0700
+++ b/src/share/classes/java/util/Vector.java Mon Mar 10 23:23:48 2008 -0700
@@ -64,15 +64,15 @@ package java.util;
*
* <p>As of the Java 2 platform v1.2, this class was retrofitted to
* implement the {@link List} interface, making it a member of the
- * <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java
- * Collections Framework</a>. Unlike the new collection
- * implementations, {@code Vector} is synchronized.
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
+ * Java Collections Framework</a>. Unlike the new collection
+ * implementations, {@code Vector} is synchronized. If a thread-safe
+ * implementation is not needed, it is recommended to use {@link
+ * ArrayList} in place of {@code Vector}.
*
* @author Lee Boynton
* @author Jonathan Payne
* @see Collection
- * @see List
- * @see ArrayList
* @see LinkedList
* @since JDK1.0
*/