diff --git a/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java b/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java index 3029bcab656..6d5ff0bdd89 100644 --- a/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java +++ b/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java @@ -24,6 +24,9 @@ import org.apache.lucene.search.DocIdSet; import org.apache.lucene.search.FieldComparator; import org.apache.lucene.search.FieldComparatorSource; import org.apache.lucene.search.Filter; +import org.apache.lucene.search.IndexSearcher; // javadocs +import org.apache.lucene.search.Query; // javadocs +import org.apache.lucene.search.ScoreDoc; // javadocs import org.apache.lucene.search.Scorer; import org.apache.lucene.search.Sort; import org.apache.lucene.search.SortField; @@ -32,12 +35,12 @@ import org.apache.lucene.util.FixedBitSet; /** * Helper class to sort readers that contain blocks of documents. *
- * Note that this currently has some limitations: + * Note that this class is intended to used with {@link SortingMergePolicy}, + * and for other purposes has some limitations: *
- * NOTE: the {@link Collector} detects sorted segments according to + * NOTE: the {@code Collector} detects sorted segments according to * {@link SortingMergePolicy}, so it's best used in conjunction with it. Also, - * it collects up to a specified num docs from each segment, and therefore is - * mostly suitable for use in conjunction with collectors such as + * it collects up to a specified {@code numDocsToCollect} from each segment, + * and therefore is mostly suitable for use in conjunction with collectors such as * {@link TopDocsCollector}, and not e.g. {@link TotalHitCountCollector}. *
- * NOTE: If you wrap a {@link TopDocsCollector} that sorts in the same - * order as the index order, the returned {@link TopDocsCollector#topDocs()} + * NOTE: If you wrap a {@code TopDocsCollector} that sorts in the same + * order as the index order, the returned {@link TopDocsCollector#topDocs() TopDocs} * will be correct. However the total of {@link TopDocsCollector#getTotalHits() * hit count} will be underestimated since not all matching documents will have * been collected. *
- * NOTE: 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 + * NOTE: This {@code Collector} uses {@link Sort#toString()} to detect + * whether a segment was sorted with the same {@code Sort}. This has * two implications: *
NOTE: Never use this {@link MergePolicy} if you rely on - * {@link IndexWriter#addDocuments(Iterable, org.apache.lucene.analysis.Analyzer)} + *
NOTE: Never use this policy if you rely on + * {@link IndexWriter#addDocuments(Iterable, Analyzer) IndexWriter.addDocuments} * to have sequentially-assigned doc IDs, this policy will scatter doc IDs. - *
NOTE: This {@link MergePolicy} should only be used with idempotent - * {@link Sort}s so that the order of segments is predictable. For example, - * using {@link SortingMergePolicy} with {@link Sort#INDEXORDER in reverse} (which is - * not idempotent) will make the order of documents in a segment depend on the - * number of times the segment has been merged. + *
NOTE: This policy should only be used with idempotent {@code Sort}s
+ * so that the order of segments is predictable. For example, using
+ * {@link Sort#INDEXORDER} in reverse (which is not idempotent) will make
+ * the order of documents in a segment depend on the number of times the segment
+ * has been merged.
* @lucene.experimental */
public final class SortingMergePolicy extends MergePolicy {
@@ -148,7 +149,7 @@ public final class SortingMergePolicy extends MergePolicy {
}
- /** Returns true if the given reader is sorted by the given sort. */
+ /** Returns {@code true} if the given {@code reader} is sorted by the specified {@code sort}. */
public static boolean isSorted(AtomicReader reader, Sort sort) {
if (reader instanceof SegmentReader) {
final SegmentReader segReader = (SegmentReader) reader;
@@ -175,7 +176,7 @@ public final class SortingMergePolicy extends MergePolicy {
final Sorter sorter;
final Sort sort;
- /** Create a new {@link MergePolicy} that sorts documents with sort
. */
+ /** Create a new {@code MergePolicy} that sorts documents with the given {@code sort}. */
public SortingMergePolicy(MergePolicy in, Sort sort) {
this.in = in;
this.sorter = new Sorter(sort);