[Javadocs] add to o.o.search.rescore,searchafter,slice, sort, and sug…

…gest (#3264)

Adds class level javadocs to org.opensearch.search, and
org.opensearch.search.rescore, searchAfter, slice, sort, and suggest
subpackages.

Signed-off-by: Nicholas Walter Knize <[email protected]>
(cherry picked from commit 3b71ea6)

server/src/main/java/org/opensearch/search/DefaultSearchContext.java

@@ -99,6 +99,11 @@
 import java.util.concurrent.Executor;
 import java.util.function.LongSupplier;
 
+/**
+ * The main search context used during search phase
+ *
+ * @opensearch.internal
+ */
 final class DefaultSearchContext extends SearchContext {
 
     private final ReaderContext readerContext;

server/src/main/java/org/opensearch/search/DocValueFormat.java

@@ -63,7 +63,11 @@
 import java.util.Objects;
 import java.util.function.LongSupplier;
 
-/** A formatter for values as returned by the fielddata/doc-values APIs. */
+/**
+ * A formatter for values as returned by the fielddata/doc-values APIs.
+ *
+ * @opensearch.internal
+ */
 public interface DocValueFormat extends NamedWriteable {
     long MASK_2_63 = 0x8000000000000000L;
     BigInteger BIGINTEGER_2_64_MINUS_ONE = BigInteger.ONE.shiftLeft(64).subtract(BigInteger.ONE); // 2^64 -1

server/src/main/java/org/opensearch/search/MultiValueMode.java

@@ -58,6 +58,8 @@
 
 /**
  * Defines what values to pick in the case a document contains multiple values for a particular field.
+ *
+ * @opensearch.internal
  */
 public enum MultiValueMode implements Writeable {
     /**

server/src/main/java/org/opensearch/search/RescoreDocIds.java

@@ -45,6 +45,8 @@
  * Since {@link org.opensearch.search.internal.SearchContext} no longer hold the states of search, the top K results
  * (i.e., documents that will be rescored by query rescorers) need to be serialized/ deserialized between search phases.
  * A {@link RescoreDocIds} encapsulates the top K results for each rescorer by its ordinal index.
+ *
+ * @opensearch.internal
  */
 public final class RescoreDocIds implements Writeable {
     public static final RescoreDocIds EMPTY = new RescoreDocIds(Collections.emptyMap());

server/src/main/java/org/opensearch/search/Scroll.java

@@ -44,7 +44,7 @@
  * A scroll enables scrolling of search request. It holds a {@link #keepAlive()} time that
  * will control how long to keep the scrolling resources open.
  *
- *
+ * @opensearch.internal
  */
 public final class Scroll implements Writeable {
 

server/src/main/java/org/opensearch/search/SearchContextMissingException.java

@@ -40,6 +40,11 @@
 
 import java.io.IOException;
 
+/**
+ * Error thrown if no search context is available
+ *
+ * @opensearch.internal
+ */
 public class SearchContextMissingException extends OpenSearchException {
 
     private final ShardSearchContextId contextId;

server/src/main/java/org/opensearch/search/SearchContextSourcePrinter.java

@@ -35,6 +35,11 @@
 import org.opensearch.search.internal.SearchContext;
 import org.opensearch.tasks.Task;
 
+/**
+ * Prints the search context source
+ *
+ * @opensearch.internal
+ */
 public class SearchContextSourcePrinter {
     private final SearchContext searchContext;
 

server/src/main/java/org/opensearch/search/SearchException.java

@@ -39,6 +39,11 @@
 
 import java.io.IOException;
 
+/**
+ * Error thrown if there is a problem during search
+ *
+ * @opensearch.internal
+ */
 public class SearchException extends OpenSearchException implements OpenSearchWrapperException {
 
     private final SearchShardTarget shardTarget;

server/src/main/java/org/opensearch/search/SearchExtBuilder.java

@@ -55,6 +55,8 @@
  * of the {@link SearchExtSpec}.
  *
  * @see SearchExtSpec
+ *
+ * @opensearch.internal
  */
 public abstract class SearchExtBuilder implements NamedWriteable, ToXContentFragment {
 

server/src/main/java/org/opensearch/search/SearchHit.java

@@ -90,6 +90,8 @@
  * A single search hit.
  *
  * @see SearchHits
+ *
+ * @opensearch.internal
  */
 public final class SearchHit implements Writeable, ToXContentObject, Iterable<DocumentField> {
 

server/src/main/java/org/opensearch/search/SearchHits.java

@@ -54,6 +54,11 @@
 
 import static org.opensearch.common.xcontent.XContentParserUtils.ensureExpectedToken;
 
+/**
+ * Encapsulates the results of a search operation
+ *
+ * @opensearch.internal
+ */
 public final class SearchHits implements Writeable, ToXContentFragment, Iterable<SearchHit> {
     public static SearchHits empty() {
         return empty(true);

server/src/main/java/org/opensearch/search/SearchModule.java

@@ -317,6 +317,8 @@
 
 /**
  * Sets up things that can be done at search time like queries, aggregations, and suggesters.
+ *
+ * @opensearch.internal
  */
 public class SearchModule {
     public static final Setting<Integer> INDICES_MAX_CLAUSE_COUNT_SETTING = Setting.intSetting(

server/src/main/java/org/opensearch/search/SearchParseException.java

@@ -41,6 +41,11 @@
 
 import java.io.IOException;
 
+/**
+ * Main error thrown if there is a problem during parsing a query
+ *
+ * @opensearch.internal
+ */
 public class SearchParseException extends SearchException {
 
     public static final int UNKNOWN_POSITION = -1;

server/src/main/java/org/opensearch/search/SearchPhaseResult.java

@@ -50,6 +50,8 @@
  * request ID is particularly important since it is used to reference and maintain a context
  * across search phases to ensure the same point in time snapshot is used for querying and
  * fetching etc.
+ *
+ * @opensearch.internal
  */
 public abstract class SearchPhaseResult extends TransportResponse {
 

server/src/main/java/org/opensearch/search/SearchService.java

@@ -151,6 +151,11 @@
 import static org.opensearch.common.unit.TimeValue.timeValueMillis;
 import static org.opensearch.common.unit.TimeValue.timeValueMinutes;
 
+/**
+ * The main search service
+ *
+ * @opensearch.internal
+ */
 public class SearchService extends AbstractLifecycleComponent implements IndexEventListener {
     private static final Logger logger = LogManager.getLogger(SearchService.class);
 

server/src/main/java/org/opensearch/search/SearchShardTarget.java

@@ -46,6 +46,8 @@
 
 /**
  * The target that the search request was executed on.
+ *
+ * @opensearch.internal
  */
 public final class SearchShardTarget implements Writeable, Comparable<SearchShardTarget> {
 

server/src/main/java/org/opensearch/search/SearchSortValues.java

@@ -47,6 +47,11 @@
 import java.util.Arrays;
 import java.util.Objects;
 
+/**
+ * Values to sort during search
+ *
+ * @opensearch.internal
+ */
 public class SearchSortValues implements ToXContentFragment, Writeable {
 
     private static final Object[] EMPTY_ARRAY = new Object[0];

server/src/main/java/org/opensearch/search/SearchSortValuesAndFormats.java

@@ -41,6 +41,11 @@
 import java.io.IOException;
 import java.util.Arrays;
 
+/**
+ * Doc value and formats to sort during search
+ *
+ * @opensearch.internal
+ */
 public class SearchSortValuesAndFormats implements Writeable {
     private final Object[] rawSortValues;
     private final Object[] formattedSortValues;

server/src/main/java/org/opensearch/search/rescore/QueryRescoreMode.java

@@ -39,6 +39,11 @@
 import java.io.IOException;
 import java.util.Locale;
 
+/**
+ * What mode the rescorer should operate in
+ *
+ * @opensearch.internal
+ */
 public enum QueryRescoreMode implements Writeable {
     Avg {
         @Override

server/src/main/java/org/opensearch/search/rescore/QueryRescorer.java

@@ -47,6 +47,12 @@
 
 import static java.util.stream.Collectors.toSet;
 
+/**
+ * A concrete query rescorer used to re-rank the Top-K results of a previously
+ * executed search.
+ *
+ * @opensearch.internal
+ */
 public final class QueryRescorer implements Rescorer {
 
     public static final Rescorer INSTANCE = new QueryRescorer();

server/src/main/java/org/opensearch/search/rescore/QueryRescorerBuilder.java

@@ -50,6 +50,11 @@
 
 import static org.opensearch.index.query.AbstractQueryBuilder.parseInnerQueryBuilder;
 
+/**
+ * Builds a query rescorer object
+ *
+ * @opensearch.internal
+ */
 public class QueryRescorerBuilder extends RescorerBuilder<QueryRescorerBuilder> {
     public static final String NAME = "query";
 

server/src/main/java/org/opensearch/search/rescore/RescoreContext.java

@@ -42,6 +42,8 @@
  * Context available to the rescore while it is running. Rescore
  * implementations should extend this with any additional resources that
  * they will need while rescoring.
+ *
+ * @opensearch.internal
  */
 public class RescoreContext {
     private final int windowSize;

server/src/main/java/org/opensearch/search/rescore/RescorePhase.java

@@ -42,6 +42,8 @@
 
 /**
  * Rescore phase of a search request, used to run potentially expensive scoring models against the top matching documents.
+ *
+ * @opensearch.internal
  */
 public class RescorePhase {
 

server/src/main/java/org/opensearch/search/rescore/Rescorer.java

@@ -45,6 +45,8 @@
  * Subclasses should borrow heavily from {@link QueryRescorer} because it is
  * fairly well behaved and documents that tradeoffs that it is making. There
  * is also an {@code ExampleRescorer} that is worth looking at.
+ *
+ * @opensearch.internal
  */
 public interface Rescorer {
     /**

server/src/main/java/org/opensearch/search/rescore/RescorerBuilder.java

@@ -49,6 +49,8 @@
 
 /**
  * The abstract base builder for instances of {@link RescorerBuilder}.
+ *
+ * @opensearch.internal
  */
 public abstract class RescorerBuilder<RB extends RescorerBuilder<RB>>
     implements

server/src/main/java/org/opensearch/search/searchafter/SearchAfterBuilder.java

@@ -59,6 +59,11 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Builds a search after object
+ *
+ * @opensearch.internal
+ */
 public class SearchAfterBuilder implements ToXContentObject, Writeable {
     public static final ParseField SEARCH_AFTER = new ParseField("search_after");
     private static final Object[] EMPTY_SORT_VALUES = new Object[0];

server/src/main/java/org/opensearch/search/slice/DocValuesSliceQuery.java

@@ -52,6 +52,8 @@
  *
  * <b>NOTE</b>: With deterministic field values this query can be used across different readers safely.
  * If updates are accepted on the field you must ensure that the same reader is used for all `slice` queries.
+ *
+ * @opensearch.internal
  */
 public final class DocValuesSliceQuery extends SliceQuery {
     public DocValuesSliceQuery(String field, int id, int max) {

server/src/main/java/org/opensearch/search/slice/SliceBuilder.java

@@ -75,6 +75,8 @@
  *  (instead of {@code numShards*numSlices}).
  *  Otherwise the provided field must be a numeric and doc_values must be enabled. In that case a
  *  {@link org.opensearch.search.slice.DocValuesSliceQuery} is used to filter the results.
+ *
+ *  @opensearch.internal
  */
 public class SliceBuilder implements Writeable, ToXContentObject {
 

server/src/main/java/org/opensearch/search/slice/SliceQuery.java

@@ -39,6 +39,8 @@
 
 /**
  * An abstract {@link Query} that defines an hash function to partition the documents in multiple slices.
+ *
+ * @opensearch.internal
  */
 public abstract class SliceQuery extends Query {
     private final String field;

server/src/main/java/org/opensearch/search/slice/TermsSliceQuery.java

@@ -59,6 +59,8 @@
  * For each segment this filter enumerates the terms dictionary, computes the hash code for each term and fills
  * a bit set with the documents of all terms whose hash code matches the predicate.
  * <b>NOTE</b>: Documents with no value for that field are ignored.
+ *
+ * @opensearch.internal
  */
 public final class TermsSliceQuery extends SliceQuery {
     // Fixed seed for computing term hashCode

server/src/main/java/org/opensearch/search/sort/BucketedSort.java

@@ -92,6 +92,8 @@
  * (like {@link BigArrays#overSize(long)}) to get amortized linear number
  * of allocations and to play well with our paged arrays.
  * </p>
+ *
+ * @opensearch.internal
  */
 public abstract class BucketedSort implements Releasable {
     /**

server/src/main/java/org/opensearch/search/sort/FieldSortBuilder.java

@@ -81,6 +81,8 @@
 
 /**
  * A sort builder to sort based on a document field.
+ *
+ * @opensearch.internal
  */
 public class FieldSortBuilder extends SortBuilder<FieldSortBuilder> {
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(FieldSortBuilder.class);

server/src/main/java/org/opensearch/search/sort/GeoDistanceSortBuilder.java

@@ -84,6 +84,8 @@
 
 /**
  * A geo distance based sorting on a geo point like field.
+ *
+ * @opensearch.internal
  */
 public class GeoDistanceSortBuilder extends SortBuilder<GeoDistanceSortBuilder> {
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(GeoDistanceSortBuilder.class);

server/src/main/java/org/opensearch/search/sort/MinAndMax.java

@@ -43,6 +43,8 @@
 
 /**
  * A class that encapsulates a minimum and a maximum, that are of the same type and {@link Comparable}.
+ *
+ * @opensearch.internal
  */
 public class MinAndMax<T extends Comparable<? super T>> implements Writeable {
     private final T minValue;

server/src/main/java/org/opensearch/search/sort/NestedSortBuilder.java

@@ -47,6 +47,11 @@
 
 import static org.opensearch.search.sort.SortBuilder.parseNestedFilter;
 
+/**
+ * Builds a sort on nested objects
+ *
+ * @opensearch.internal
+ */
 public class NestedSortBuilder implements Writeable, ToXContentObject {
     public static final ParseField NESTED_FIELD = new ParseField("nested");
     public static final ParseField PATH_FIELD = new ParseField("path");

server/src/main/java/org/opensearch/search/sort/ScoreSortBuilder.java

@@ -49,6 +49,8 @@
 
 /**
  * A sort builder allowing to sort by score.
+ *
+ * @opensearch.internal
  */
 public class ScoreSortBuilder extends SortBuilder<ScoreSortBuilder> {
 

server/src/main/java/org/opensearch/search/sort/ScriptSortBuilder.java

@@ -77,6 +77,8 @@
 
 /**
  * Script sort builder allows to sort based on a custom script expression.
+ *
+ * @opensearch.internal
  */
 public class ScriptSortBuilder extends SortBuilder<ScriptSortBuilder> {
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(ScriptSortBuilder.class);

server/src/main/java/org/opensearch/search/sort/SortAndFormats.java

@@ -34,6 +34,11 @@
 import org.apache.lucene.search.Sort;
 import org.opensearch.search.DocValueFormat;
 
+/**
+ * Utility class to hold sort and doc value format instances
+ *
+ * @opensearch.internal
+ */
 public final class SortAndFormats {
 
     public final Sort sort;