Index: contrib/collation/src/java/org/apache/lucene/collation/CollationKeyAnalyzer.java
===================================================================
--- contrib/collation/src/java/org/apache/lucene/collation/CollationKeyAnalyzer.java	(revision 788923)
+++ contrib/collation/src/java/org/apache/lucene/collation/CollationKeyAnalyzer.java	(working copy)
@@ -59,12 +59,17 @@
  *   </li>
  * </ol> 
  * <p>
- *   NB 1: {@link ICUCollationKeyAnalyzer} uses ICU4J's Collator, which makes 
+ *   {@link ICUCollationKeyAnalyzer} uses ICU4J's Collator, which makes 
  *   its version available, thus allowing collation to be versioned
- *   independently from the JVM.
+ *   independently from the JVM.  ICUCollationKeyAnalyzer is also significantly
+ *   faster and generates significantly shorter keys than CollationKeyAnalyzer.
+ *   See <a href="http://site.icu-project.org/charts/collation-icu4j-sun"
+ *   >http://site.icu-project.org/charts/collation-icu4j-sun</a> for key
+ *   generation timing and key length comparisons between ICU4J and
+ *   java.text.Collator over several languages.
  * </p>
  * <p>
- *   NB 2: CollationKeys generated by java.text.Collators are not compatible
+ *   CollationKeys generated by java.text.Collators are not compatible
  *   with those those generated by ICU Collators.  Specifically, if you use 
  *   CollationKeyAnalyzer to generate index terms, do not use
  *   ICUCollationKeyAnalyzer on the query side, or vice versa.
Index: contrib/collation/src/java/org/apache/lucene/collation/CollationKeyFilter.java
===================================================================
--- contrib/collation/src/java/org/apache/lucene/collation/CollationKeyFilter.java	(revision 788923)
+++ contrib/collation/src/java/org/apache/lucene/collation/CollationKeyFilter.java	(working copy)
@@ -57,12 +57,17 @@
  *   </li>
  * </ol> 
  * <p>
- *   NB 1: {@link ICUCollationKeyFilter} uses ICU4J's Collator, which makes its
+ *   {@link ICUCollationKeyFilter} uses ICU4J's Collator, which makes its
  *   version available, thus allowing collation to be versioned independently
- *   from the JVM.
+ *   from the JVM.  ICUCollationKeyFilter is also significantly faster and
+ *   generates significantly shorter keys than CollationKeyFilter.  See
+ *   <a href="http://site.icu-project.org/charts/collation-icu4j-sun"
+ *   >http://site.icu-project.org/charts/collation-icu4j-sun</a> for key
+ *   generation timing and key length comparisons between ICU4J and
+ *   java.text.Collator over several languages.
  * </p>
  * <p>
- *   NB 2: CollationKeys generated by java.text.Collators are not compatible
+ *   CollationKeys generated by java.text.Collators are not compatible
  *   with those those generated by ICU Collators.  Specifically, if you use 
  *   CollationKeyFilter to generate index terms, do not use
  *   {@link ICUCollationKeyFilter} on the query side, or vice versa.
Index: contrib/collation/src/java/org/apache/lucene/collation/ICUCollationKeyAnalyzer.java
===================================================================
--- contrib/collation/src/java/org/apache/lucene/collation/ICUCollationKeyAnalyzer.java	(revision 788923)
+++ contrib/collation/src/java/org/apache/lucene/collation/ICUCollationKeyAnalyzer.java	(working copy)
@@ -55,11 +55,19 @@
  *   </li>
  * </ol> 
  * <p>
- *   NB: CollationKeys generated by ICU Collators are not compatible with those
+ *   CollationKeys generated by ICU Collators are not compatible with those
  *   generated by java.text.Collators.  Specifically, if you use 
  *   ICUCollationKeyAnalyzer to generate index terms, do not use 
  *   {@link CollationKeyAnalyzer} on the query side, or vice versa.
  * </p>
+ * <p>
+ *   ICUCollationKeyAnalyzer is significantly faster and generates significantly
+ *   shorter keys than CollationKeyAnalyzer.  See
+ *   <a href="http://site.icu-project.org/charts/collation-icu4j-sun"
+ *   >http://site.icu-project.org/charts/collation-icu4j-sun</a> for key
+ *   generation timing and key length comparisons between ICU4J and
+ *   java.text.Collator over several languages.
+ * </p>
  */
 public class ICUCollationKeyAnalyzer extends Analyzer {
   private Collator collator;
Index: contrib/collation/src/java/org/apache/lucene/collation/ICUCollationKeyFilter.java
===================================================================
--- contrib/collation/src/java/org/apache/lucene/collation/ICUCollationKeyFilter.java	(revision 788923)
+++ contrib/collation/src/java/org/apache/lucene/collation/ICUCollationKeyFilter.java	(working copy)
@@ -60,6 +60,14 @@
  *   ICUCollationKeyFilter to generate index terms, do not use 
  *   {@link CollationKeyFilter} on the query side, or vice versa.
  * </p>
+ * <p>
+ *   ICUCollationKeyFilter is significantly faster and generates significantly
+ *   shorter keys than CollationKeyFilter.  See
+ *   <a href="http://site.icu-project.org/charts/collation-icu4j-sun"
+ *   >http://site.icu-project.org/charts/collation-icu4j-sun</a> for key
+ *   generation timing and key length comparisons between ICU4J and
+ *   java.text.Collator over several languages.
+ * </p>
  */
 public class ICUCollationKeyFilter extends TokenFilter {
   private Collator collator = null;