LUCENE-5493: javadocs

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/branches/lucene5493@1574954 13f79535-47bb-0310-9956-ffa450edef68

lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java

@@ -31,7 +31,7 @@ import org.apache.lucene.search.TotalHitCountCollector;
 /**
  * A {@link Collector} that early terminates collection of documents on a
  * per-segment basis, if the segment was sorted according to the given
- * {@link Sorter}.
+ * {@link Sort}.
  * 
  * <p>
  * <b>NOTE:</b> the {@link Collector} detects sorted segments according to
@@ -46,23 +46,22 @@ import org.apache.lucene.search.TotalHitCountCollector;
  * hit count} will be underestimated since not all matching documents will have
  * been collected.
  * <p>
- * <b>NOTE</b>: This {@link Collector} uses {@link Sorter#getID()} to detect
- * whether a segment was sorted with the same {@link Sorter} as the one given in
+ * <b>NOTE</b>: This {@link Collector} uses {@link Sort#toString()} to detect
+ * whether a segment was sorted with the same {@link Sort} as the one given in
  * {@link #EarlyTerminatingSortingCollector(Collector, Sort, int)}. This has
  * two implications:
  * <ul>
- * <li>if {@link Sorter#getID()} is not implemented correctly and returns
- * different identifiers for equivalent {@link Sorter}s, this collector will not
+ * <li>if a custom comparator is not implemented correctly and returns
+ * different identifiers for equivalent instances, this collector will not
  * detect sorted segments,</li>
  * <li>if you suddenly change the {@link IndexWriter}'s
  * {@link SortingMergePolicy} to sort according to another criterion and if both
- * the old and the new {@link Sorter}s have the same identifier, this
+ * the old and the new {@link Sort}s have the same identifier, this
  * {@link Collector} will incorrectly detect sorted segments.</li>
  * </ul>
  * 
  * @lucene.experimental
  */
-// nocommit: fix these javadocs to be about Sort
 public class EarlyTerminatingSortingCollector extends Collector {
 
   protected final Collector in;

lucene/misc/src/java/org/apache/lucene/index/sorter/Sorter.java

@@ -47,19 +47,19 @@ final class Sorter {
    * {@link IndexReader#maxDoc()}, <code>oldToNew(newToOld(docID))</code> must
    * return <code>docID</code>.
    */
-  public static abstract class DocMap {
+  static abstract class DocMap {
 
     /** Given a doc ID from the original index, return its ordinal in the
      *  sorted index. */
-    public abstract int oldToNew(int docID);
+    abstract int oldToNew(int docID);
 
     /** Given the ordinal of a doc ID, return its doc ID in the original index. */
-    public abstract int newToOld(int docID);
+    abstract int newToOld(int docID);
 
     /** Return the number of documents in this map. This must be equal to the
      *  {@link AtomicReader#maxDoc() number of documents} of the
      *  {@link AtomicReader} which is sorted. */
-    public abstract int size();
+    abstract int size();
   }
 
   /** Check consistency of a {@link DocMap}, useful for assertions. */
@@ -78,7 +78,7 @@ final class Sorter {
   }
 
   /** A comparator of doc IDs. */
-  public static abstract class DocComparator {
+  static abstract class DocComparator {
 
     /** Compare docID1 against docID2. The contract for the return value is the
      *  same as {@link Comparator#compare(Object, Object)}. */
@@ -92,7 +92,7 @@ final class Sorter {
     private final Sorter.DocComparator comparator;
     private final int[] tmp;
     
-    public DocValueSorter(int[] docs, Sorter.DocComparator comparator) {
+    DocValueSorter(int[] docs, Sorter.DocComparator comparator) {
       super(docs.length / 64);
       this.docs = docs;
       this.comparator = comparator;
@@ -133,7 +133,7 @@ final class Sorter {
   }
 
   /** Computes the old-to-new permutation over the given comparator. */
-  protected static Sorter.DocMap sort(final int maxDoc, DocComparator comparator) {
+  private static Sorter.DocMap sort(final int maxDoc, DocComparator comparator) {
     // check if the index is sorted
     boolean sorted = true;
     for (int i = 1; i < maxDoc; ++i) {
@@ -207,7 +207,7 @@ final class Sorter {
    * <b>NOTE:</b> deleted documents are expected to appear in the mapping as
    * well, they will however be marked as deleted in the sorted view.
    */
-  public DocMap sort(AtomicReader reader) throws IOException {
+  DocMap sort(AtomicReader reader) throws IOException {
     SortField fields[] = sort.getSort();
     final int reverseMul[] = new int[fields.length];
     final FieldComparator<?> comparators[] = new FieldComparator[fields.length];
@@ -246,7 +246,7 @@ final class Sorter {
    * <p>This identifier is similar to {@link Object#hashCode()} and should be
    * chosen so that two instances of this class that sort documents likewise
    * will have the same identifier. On the contrary, this identifier should be
-   * different on different {@link Sorter sorters}.
+   * different on different {@link Sort sorts}.
    */
   public String getID() {
     return sort.toString();

lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java

@@ -51,7 +51,6 @@ import org.apache.lucene.util.packed.MonotonicAppendingLongBuffer;
  *  not idempotent) will make the order of documents in a segment depend on the
  *  number of times the segment has been merged.
  *  @lucene.experimental */
-// nocommit: fix these jdocs around idempotency
 public final class SortingMergePolicy extends MergePolicy {
 
   /**

lucene/misc/src/java/org/apache/lucene/index/sorter/package.html

@@ -17,19 +17,16 @@
 -->
 <html>
 <body>
-<p>Provides index sorting capablities. The application can use one of the
-pre-existing Sorter implementations, e.g. to sort by a
-{@link org.apache.lucene.index.sorter.NumericDocValuesSorter}
-or {@link org.apache.lucene.index.sorter.Sorter#REVERSE_DOCS reverse} the order
-of the documents. Additionally, the application can implement a custom
-{@link org.apache.lucene.index.sorter.Sorter} which returns a permutation on 
-a source {@link org.apache.lucene.index.AtomicReader}'s document IDs, to sort
-the input documents by additional criteria.
+<p>Provides index sorting capablities. The application can use any
+Sort specification, e.g. to sort by fields using DocValues or FieldCache, or to
+reverse the order of the documents (by using SortField.Type.DOC in reverse).
+Multi-level sorts can be specified the same way you would when searching, by
+building Sort from multiple SortFields.
 
 <p>{@link org.apache.lucene.index.sorter.SortingMergePolicy} can be used to
 make Lucene sort segments before merging them. This will ensure that every
 segment resulting from a merge will be sorted according to the provided
-{@link org.apache.lucene.index.sorter.Sorter}. This however makes merging and
+{@link org.apache.lucene.search.Sort}. This however makes merging and
 thus indexing slower.
 
 <p>Sorted segments allow for early query termination when the sort order