svn commit: r526550 - /lucene/java/trunk/src/java/org/apache/lucene/search/Hits.java

[dn...@apache.org]

Author: dnaber
Date: Sun Apr  8 06:17:10 2007
New Revision: 526550

URL: http://svn.apache.org/viewvc?view=rev&rev=526550
Log:
small javadoc improvements about ids and performance

Modified:
    lucene/java/trunk/src/java/org/apache/lucene/search/Hits.java

Modified: lucene/java/trunk/src/java/org/apache/lucene/search/Hits.java
URL: http://svn.apache.org/viewvc/lucene/java/trunk/src/java/org/apache/lucene/search/Hits.java?view=diff&rev=526550&r1=526549&r2=526550
==============================================================================
--- lucene/java/trunk/src/java/org/apache/lucene/search/Hits.java (original)
+++ lucene/java/trunk/src/java/org/apache/lucene/search/Hits.java Sun Apr  8 06:17:10 2007
@@ -24,7 +24,14 @@
 import org.apache.lucene.document.Document;
 import org.apache.lucene.index.CorruptIndexException;
 
-/** A ranked list of documents, used to hold search results. */
+/** A ranked list of documents, used to hold search results.
+ * <p>
+ * <b>Caution:</b> Iterate only over the hits needed.  Iterating over all
+ * hits is generally not desirable and may be the source of
+ * performance issues. If you need to iterate over many or all hits, consider
+ * using the search method that takes a {@link HitCollector}.
+ * </p>
+ */
 public final class Hits {
   private Weight weight;
   private Searcher searcher;
@@ -111,12 +118,15 @@
     return hitDoc.doc;
   }
 
-  /** Returns the score for the nth document in this set. */
+  /** Returns the score for the n<sup>th</sup> document in this set. */
   public final float score(int n) throws IOException {
     return hitDoc(n).score;
   }
 
-  /** Returns the id for the nth document in this set. */
+  /** Returns the id for the n<sup>th</sup> document in this set.
+   * Note that ids may change when the index changes, so you cannot
+   * rely on the id to be stable.
+   */
   public final int id(int n) throws IOException {
     return hitDoc(n).id;
   }
@@ -127,7 +137,8 @@
    * <p>
    * <b>Caution:</b> Iterate only over the hits needed.  Iterating over all
    * hits is generally not desirable and may be the source of
-   * performance issues.
+   * performance issues. If you need to iterate over many or all hits, consider
+   * using a search method that takes a {@link HitCollector}.
    * </p>
    */
   public Iterator iterator() {