From 3c586d3528dfa18d448fd21effca97be94028796 Mon Sep 17 00:00:00 2001
From: Mark Robert Miller <markrmiller@apache.org>
Date: Sun, 2 Aug 2009 17:59:21 +0000
Subject: [PATCH] LUCENE-1764: beef up javadoc with warning

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@800119 13f79535-47bb-0310-9956-ffa450edef68
---
 .../apache/lucene/search/SortComparator.java  | 36 +++++++++++--------
 .../lucene/search/SortComparatorSource.java   | 18 +++++++---
 2 files changed, 35 insertions(+), 19 deletions(-)

diff --git a/src/java/org/apache/lucene/search/SortComparator.java b/src/java/org/apache/lucene/search/SortComparator.java
index f2a8006b71a..acb555323c0 100644
--- a/src/java/org/apache/lucene/search/SortComparator.java
+++ b/src/java/org/apache/lucene/search/SortComparator.java
@@ -23,21 +23,29 @@ import java.io.IOException;
 
 /**
  * Abstract base class for sorting hits returned by a Query.
- *
- * <p>This class should only be used if the other SortField
- * types (SCORE, DOC, STRING, INT, FLOAT) do not provide an
- * adequate sorting.  It maintains an internal cache of values which
- * could be quite large.  The cache is an array of Comparable,
- * one for each document in the index.  There is a distinct
- * Comparable for each unique term in the field - if
- * some documents have the same term in the field, the cache
- * array will have entries which reference the same Comparable.
- *
- * <p>Created: Apr 21, 2004 5:08:38 PM
- *
- *
+ * 
+ * <p>
+ * This class should only be used if the other SortField types (SCORE, DOC,
+ * STRING, INT, FLOAT) do not provide an adequate sorting. It maintains an
+ * internal cache of values which could be quite large. The cache is an array of
+ * Comparable, one for each document in the index. There is a distinct
+ * Comparable for each unique term in the field - if some documents have the
+ * same term in the field, the cache array will have entries which reference the
+ * same Comparable.
+ * 
+ * This class will be used as part of a key to a FieldCache value. You must
+ * implement hashCode and equals to avoid an explosion in RAM usage if you use
+ * instances that are not the same instance. If you are searching using the
+ * Remote contrib, the same instance of this class on the client will be a new
+ * instance on every call to the server, so hashCode/equals is very important in
+ * that situation.
+ * 
+ * <p>
+ * Created: Apr 21, 2004 5:08:38 PM
+ * 
+ * 
  * @version $Id$
- * @since   1.4
+ * @since 1.4
  * @deprecated Please use {@link FieldComparatorSource} instead.
  */
 public abstract class SortComparator
diff --git a/src/java/org/apache/lucene/search/SortComparatorSource.java b/src/java/org/apache/lucene/search/SortComparatorSource.java
index 219f87a8a39..d7c8992db40 100644
--- a/src/java/org/apache/lucene/search/SortComparatorSource.java
+++ b/src/java/org/apache/lucene/search/SortComparatorSource.java
@@ -23,12 +23,20 @@ import java.io.Serializable;
 
 /**
  * Expert: returns a comparator for sorting ScoreDocs.
- *
- * <p>Created: Apr 21, 2004 3:49:28 PM
  * 
- *
- * @version $Id$
- * @since   1.4
+ * <p>
+ * Created: Apr 21, 2004 3:49:28 PM
+ * 
+ * This class will be used as part of a key to a FieldCache value. You must
+ * implement hashCode and equals to avoid an explosion in RAM usage if you use
+ * instances that are not the same instance. If you are searching using the
+ * Remote contrib, the same instance of this class on the client will be a new
+ * instance on every call to the server, so hashCode/equals is very important in
+ * that situation.
+ * 
+ * @version $Id: SortComparatorSource.java 747019 2009-02-23 13:59:50Z
+ *          mikemccand $
+ * @since 1.4
  * @deprecated Please use {@link FieldComparatorSource} instead.
  */
 public interface SortComparatorSource