svn commit: r1403105 - /lucene/dev/branches/LUCENE-2878/lucene/core/src/java/org/apache/lucene/search/Scorer.java

[mi...@apache.org]

Author: mikemccand
Date: Sun Oct 28 21:58:52 2012
New Revision: 1403105

URL: http://svn.apache.org/viewvc?rev=1403105&view=rev
Log:
LUCENE-2878: improve javadocs

Modified:
    lucene/dev/branches/LUCENE-2878/lucene/core/src/java/org/apache/lucene/search/Scorer.java

Modified: lucene/dev/branches/LUCENE-2878/lucene/core/src/java/org/apache/lucene/search/Scorer.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/LUCENE-2878/lucene/core/src/java/org/apache/lucene/search/Scorer.java?rev=1403105&r1=1403104&r2=1403105&view=diff
==============================================================================
--- lucene/dev/branches/LUCENE-2878/lucene/core/src/java/org/apache/lucene/search/Scorer.java (original)
+++ lucene/dev/branches/LUCENE-2878/lucene/core/src/java/org/apache/lucene/search/Scorer.java Sun Oct 28 21:58:52 2012
@@ -67,16 +67,13 @@ public abstract class Scorer extends Doc
   
   /**
    * Expert: Retrieves an {@link IntervalIterator} for this scorer allowing
-   * access to position and offset intervals for each matching document. The
-   * returned iterator is aligned with the scorer that created the iterator and
-   * should only be advanced to the currently matched document.
-   * 
-   * <p>
-   * Note: {@link IntervalIterator} can be pulled multiple times from a scorer.
-   * Yet, there should only be one iterator advanced on the same document. It is
-   * recommended that the caller maintains a single interval iterator per
-   * scorer.
-   * </p>
+   * access to position and offset intervals for each
+   * matching document.  Call this up-front and use it as
+   * long as you are still using this scorer.  The
+   * returned iterator is bound to scorer that created it;
+   * after {@link #nextDoc} or {@link #advance} you must
+   * call {@link IntervalIterator#scorerAdvanced} before
+   * iterating over that document's intervals.
    * 
    * @param collectIntervals
    *          if <code>true</code> the {@link IntervalIterator} can be used to
@@ -86,6 +83,8 @@ public abstract class Scorer extends Doc
    * @return an {@link IntervalIterator} over matching intervals
    * @throws IOException
    *           if a low-level I/O error is encountered
+   *
+   * @lucene.experimental
    */
   public abstract IntervalIterator intervals(boolean collectIntervals) throws IOException;