improve javadocs for Collector.acceptsDocsOutOfOrder

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@884870 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/lucene/search/Collector.java

@@ -157,14 +157,20 @@ public abstract class Collector {
   public abstract void setNextReader(IndexReader reader, int docBase) throws IOException;
 
   /**
-   * Returns true iff this {@link Collector} can accept documents given to
+   * Return <code>true</code> if this collector does not
-   * {@link #collect(int)} out of order.
+   * require the matching docIDs to be delivered in int sort
-   * <p>
+   * order (smallest to largest) to {@link #collect}.
-   * NOTE: some collectors can work in either mode, with a more efficient
+   *
-   * implementation for in-order docs collection. If your collector can work in
+   * <p> Most Lucene Query implementations will visit
-   * either mode, it is recommended that you create two variants of it, since
+   * matching docIDs in order.  However, some queries
-   * some queries work much faster if out-of-order collection is supported by a
+   * (currently limited to certain cases of {@link
-   * {@link Collector}.
+   * BooleanQuery}) can achieve faster searching if the
+   * <code>Collector</code> allows them to deliver the
+   * docIDs out of order.</p>
+   *
+   * <p> Many collectors don't mind getting docIDs out of
+   * order, so it's important to return <code>true</code>
+   * here.
    */
   public abstract boolean acceptsDocsOutOfOrder();