Document that the compact collections aren't universal wins.

RELNOTES=n/a

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=185590939

android/guava/src/com/google/common/collect/CompactHashMap.java

@@ -59,6 +59,11 @@
  * {@link #values} views is the same as insertion order. Any removal invalidates any ordering
  * guarantees.
  *
+ * <p>This class should not be assumed to be universally superior to {@code java.util.HashMap}.
+ * Generally speaking, this class reduces object allocation and memory consumption at the price of
+ * moderately increased constant factors of CPU.  Only use this class when there is a specific
+ * reason to prioritize memory over CPU.
+ *
  * @author Louis Wasserman
  */
 @GwtIncompatible // not worth using in GWT for now

android/guava/src/com/google/common/collect/CompactHashSet.java

@@ -56,6 +56,11 @@
  * <p>If there are no removals, then {@link #iterator iteration} order is the same as insertion
  * order. Any removal invalidates any ordering guarantees.
  *
+ * <p>This class should not be assumed to be universally superior to {@code java.util.HashSet}.
+ * Generally speaking, this class reduces object allocation and memory consumption at the price of
+ * moderately increased constant factors of CPU.  Only use this class when there is a specific
+ * reason to prioritize memory over CPU.
+ *
  * @author Dimitris Andreou
  */
 @GwtIncompatible // not worth using in GWT for now

android/guava/src/com/google/common/collect/CompactLinkedHashMap.java

@@ -27,11 +27,16 @@
  *
  * <p>{@code containsKey(k)}, {@code put(k, v)} and {@code remove(k)} are all (expected and
  * amortized) constant time operations. Expected in the hashtable sense (depends on the hash
- * function doing a good job of distributing the elements to the buckets to a distribution not
- * far from uniform), and amortized since some operations can trigger a hash table resize.
+ * function doing a good job of distributing the elements to the buckets to a distribution not far
+ * from uniform), and amortized since some operations can trigger a hash table resize.
  *
- * <p>As compared with {@link java.util.LinkedHashMap}, this structure places significantly
- * reduced load on the garbage collector by only using a constant number of internal objects.
+ * <p>As compared with {@link java.util.LinkedHashMap}, this structure places significantly reduced
+ * load on the garbage collector by only using a constant number of internal objects.
+ *
+ * <p>This class should not be assumed to be universally superior to {@code
+ * java.util.LinkedHashMap}. Generally speaking, this class reduces object allocation and memory
+ * consumption at the price of moderately increased constant factors of CPU. Only use this class
+ * when there is a specific reason to prioritize memory over CPU.
  *
  * @author Louis Wasserman
  */

android/guava/src/com/google/common/collect/CompactLinkedHashSet.java

@@ -23,19 +23,23 @@
 import org.checkerframework.checker.nullness.compatqual.MonotonicNonNullDecl;
 
 /**
- * CompactLinkedHashSet is an implementation of a Set, which a predictable iteration order
- * that matches the insertion order. All optional operations (adding and
- * removing) are supported. All elements, including {@code null}, are permitted.
+ * CompactLinkedHashSet is an implementation of a Set, which a predictable iteration order that
+ * matches the insertion order. All optional operations (adding and removing) are supported. All
+ * elements, including {@code null}, are permitted.
  *
  * <p>{@code contains(x)}, {@code add(x)} and {@code remove(x)}, are all (expected and amortized)
- * constant time operations. Expected in the hashtable sense (depends on the hash function
- * doing a good job of distributing the elements to the buckets to a distribution not far from
- * uniform), and amortized since some operations can trigger a hash table resize.
+ * constant time operations. Expected in the hashtable sense (depends on the hash function doing a
+ * good job of distributing the elements to the buckets to a distribution not far from uniform), and
+ * amortized since some operations can trigger a hash table resize.
  *
- * <p>This implementation consumes significantly less memory than {@code java.util.LinkedHashSet}
- * or even {@code java.util.HashSet}, and places considerably less load on the garbage collector.
- * Like {@code java.util.LinkedHashSet}, it offers insertion-order iteration, with identical
- * behavior.
+ * <p>This implementation consumes significantly less memory than {@code java.util.LinkedHashSet} or
+ * even {@code java.util.HashSet}, and places considerably less load on the garbage collector. Like
+ * {@code java.util.LinkedHashSet}, it offers insertion-order iteration, with identical behavior.
+ *
+ * <p>This class should not be assumed to be universally superior to {@code
+ * java.util.LinkedHashSet}. Generally speaking, this class reduces object allocation and memory
+ * consumption at the price of moderately increased constant factors of CPU. Only use this class
+ * when there is a specific reason to prioritize memory over CPU.
  *
  * @author Louis Wasserman
  */

guava/src/com/google/common/collect/CompactHashMap.java

@@ -64,6 +64,11 @@
  * {@link #values} views is the same as insertion order. Any removal invalidates any ordering
  * guarantees.
  *
+ * <p>This class should not be assumed to be universally superior to {@code java.util.HashMap}.
+ * Generally speaking, this class reduces object allocation and memory consumption at the price of
+ * moderately increased constant factors of CPU.  Only use this class when there is a specific
+ * reason to prioritize memory over CPU.
+ *
  * @author Louis Wasserman
  */
 @GwtIncompatible // not worth using in GWT for now

guava/src/com/google/common/collect/CompactHashSet.java

@@ -60,6 +60,11 @@
  * <p>If there are no removals, then {@link #iterator iteration} order is the same as insertion
  * order. Any removal invalidates any ordering guarantees.
  *
+ * <p>This class should not be assumed to be universally superior to {@code java.util.HashSet}.
+ * Generally speaking, this class reduces object allocation and memory consumption at the price of
+ * moderately increased constant factors of CPU.  Only use this class when there is a specific
+ * reason to prioritize memory over CPU.
+ *
  * @author Dimitris Andreou
  */
 @GwtIncompatible // not worth using in GWT for now

guava/src/com/google/common/collect/CompactLinkedHashMap.java

@@ -36,11 +36,16 @@
  *
  * <p>{@code containsKey(k)}, {@code put(k, v)} and {@code remove(k)} are all (expected and
  * amortized) constant time operations. Expected in the hashtable sense (depends on the hash
- * function doing a good job of distributing the elements to the buckets to a distribution not
- * far from uniform), and amortized since some operations can trigger a hash table resize.
+ * function doing a good job of distributing the elements to the buckets to a distribution not far
+ * from uniform), and amortized since some operations can trigger a hash table resize.
  *
- * <p>As compared with {@link java.util.LinkedHashMap}, this structure places significantly
- * reduced load on the garbage collector by only using a constant number of internal objects.
+ * <p>As compared with {@link java.util.LinkedHashMap}, this structure places significantly reduced
+ * load on the garbage collector by only using a constant number of internal objects.
+ *
+ * <p>This class should not be assumed to be universally superior to {@code
+ * java.util.LinkedHashMap}. Generally speaking, this class reduces object allocation and memory
+ * consumption at the price of moderately increased constant factors of CPU. Only use this class
+ * when there is a specific reason to prioritize memory over CPU.
  *
  * @author Louis Wasserman
  */

guava/src/com/google/common/collect/CompactLinkedHashSet.java

@@ -28,19 +28,23 @@
 import org.checkerframework.checker.nullness.compatqual.MonotonicNonNullDecl;
 
 /**
- * CompactLinkedHashSet is an implementation of a Set, which a predictable iteration order
- * that matches the insertion order. All optional operations (adding and
- * removing) are supported. All elements, including {@code null}, are permitted.
+ * CompactLinkedHashSet is an implementation of a Set, which a predictable iteration order that
+ * matches the insertion order. All optional operations (adding and removing) are supported. All
+ * elements, including {@code null}, are permitted.
  *
  * <p>{@code contains(x)}, {@code add(x)} and {@code remove(x)}, are all (expected and amortized)
- * constant time operations. Expected in the hashtable sense (depends on the hash function
- * doing a good job of distributing the elements to the buckets to a distribution not far from
- * uniform), and amortized since some operations can trigger a hash table resize.
+ * constant time operations. Expected in the hashtable sense (depends on the hash function doing a
+ * good job of distributing the elements to the buckets to a distribution not far from uniform), and
+ * amortized since some operations can trigger a hash table resize.
  *
- * <p>This implementation consumes significantly less memory than {@code java.util.LinkedHashSet}
- * or even {@code java.util.HashSet}, and places considerably less load on the garbage collector.
- * Like {@code java.util.LinkedHashSet}, it offers insertion-order iteration, with identical
- * behavior.
+ * <p>This implementation consumes significantly less memory than {@code java.util.LinkedHashSet} or
+ * even {@code java.util.HashSet}, and places considerably less load on the garbage collector. Like
+ * {@code java.util.LinkedHashSet}, it offers insertion-order iteration, with identical behavior.
+ *
+ * <p>This class should not be assumed to be universally superior to {@code
+ * java.util.LinkedHashSet}. Generally speaking, this class reduces object allocation and memory
+ * consumption at the price of moderately increased constant factors of CPU. Only use this class
+ * when there is a specific reason to prioritize memory over CPU.
  *
  * @author Louis Wasserman
  */