Add documentation

Signed-off-by: Vijayan Balasubramanian <[email protected]>

src/main/java/org/opensearch/neuralsearch/executors/HybridQueryExecutor.java

@@ -21,8 +21,9 @@ public class HybridQueryExecutor {
     private static TaskExecutor taskExecutor;
 
     /**
-     * @param settings OpenSearch settings
-     * @return the executor builder
+     * Provide fixed executor builder to use for hybrid query executors
+     * @param settings Node level settings
+     * @return the executor builder for hybrid query's custom thread pool.
      */
     public static ExecutorBuilder getExecutorBuilder(final Settings settings) {
         final int allocatedProcessors = OpenSearchExecutors.allocatedProcessors(settings);
@@ -35,6 +36,10 @@ public static ExecutorBuilder getExecutorBuilder(final Settings settings) {
         );
     }
 
+    /**
+     * Initialize @{@link TaskExecutor} to run tasks concurrently using {@link ThreadPool}
+     * @param threadPool OpenSearch's thread pool instance
+     */
     public static void initialize(@NonNull ThreadPool threadPool) {
         if (threadPool == null) {
             throw new IllegalArgumentException("Argument thread-pool cannot be null");
@@ -44,8 +49,7 @@ public static void initialize(@NonNull ThreadPool threadPool) {
 
     /**
      * Return TaskExecutor Wrapper that helps runs tasks concurrently
-     *
-     * @return the executor service
+     * @return TaskExecutor instance to help run search tasks in parallel
      */
     public static TaskExecutor getExecutor() {
         return taskExecutor;

src/main/java/org/opensearch/neuralsearch/executors/HybridQueryExecutorCollector.java

@@ -10,6 +10,10 @@
 
 import java.util.function.Function;
 
+/**
+ * {@link HybridQueryExecutorCollector} is a generic Collector used by Hybrid Search Query during
+ * Query phase to parallelize sub query's action to improve latency
+ */
 @RequiredArgsConstructor(staticName = "newCollector")
 public class HybridQueryExecutorCollector<I, R> {
     @NonNull

src/main/java/org/opensearch/neuralsearch/executors/HybridQueryExecutorCollectorManager.java

@@ -4,6 +4,9 @@
  */
 package org.opensearch.neuralsearch.executors;
 
+/**
+ * {@link HybridQueryExecutorCollectorManager} is responsible for creating new {@link HybridQueryExecutorCollector} instances
+ */
 public interface HybridQueryExecutorCollectorManager<C extends HybridQueryExecutorCollector, R> {
     C newCollector();
 }

src/main/java/org/opensearch/neuralsearch/query/HybridQueryRewriteCollectorManager.java

@@ -15,22 +15,41 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+/**
+ * {@link HybridQueryRewriteCollectorManager} is responsible for creating {@link HybridQueryExecutorCollector}
+ * instances. Useful to create {@link HybridQueryExecutorCollector} instances that rewrites {@link Query} into primitive
+ * {@link Query} using {@link IndexSearcher}
+ */
 @RequiredArgsConstructor
 public class HybridQueryRewriteCollectorManager
     implements
         HybridQueryExecutorCollectorManager<HybridQueryExecutorCollector, Map.Entry<Query, Boolean>> {
 
     private @NonNull IndexSearcher searcher;
 
+    /**
+     * Returns new {@link HybridQueryExecutorCollector} to facilitate parallel execution
+     * @return HybridQueryExecutorCollector instance
+     */
     @Override
     public HybridQueryExecutorCollector<IndexSearcher, Map.Entry<Query, Boolean>> newCollector() {
         return HybridQueryExecutorCollector.newCollector(searcher);
     }
 
+    /**
+     * Returns list of {@link Query} that were rewritten by collectors
+     * @param collectors
+     * @return
+     */
     public List<Query> getRewriteQueries(List<HybridQueryExecutorCollector<IndexSearcher, Map.Entry<Query, Boolean>>> collectors) {
         return collectors.stream().map(collector -> collector.getResult().getKey()).collect(Collectors.toList());
     }
 
+    /**
+     * Returns true if any of the {@link Query} from collector were actually rewritten.
+     * @param collectors
+     * @return at least one query is rewritten by any of the collectors
+     */
     public Boolean anyQueryRewrite(List<HybridQueryExecutorCollector<IndexSearcher, Map.Entry<Query, Boolean>>> collectors) {
         // return true if at least one query is rewritten
         return collectors.stream().anyMatch(collector -> collector.getResult().getValue());

src/main/java/org/opensearch/neuralsearch/query/HybridQueryScoreSupplierCollectorManager.java

@@ -14,18 +14,34 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * HybridQueryScoreSupplierCollectorManager is responsible for creating {@link HybridQueryExecutorCollector} instances.
+ * Useful to create {@link HybridQueryExecutorCollector} instances that build {@link ScorerSupplier} from
+ * given weight.
+ */
 @RequiredArgsConstructor
 public class HybridQueryScoreSupplierCollectorManager
     implements
         HybridQueryExecutorCollectorManager<HybridQueryExecutorCollector<LeafReaderContext, ScorerSupplier>, ScorerSupplier> {
 
     private @NonNull LeafReaderContext context;
 
+    /**
+     * Creates new {@link HybridQueryExecutorCollector} instance everytime to facilitate parallel execution
+     * by individual tasks
+     * @return new instance of HybridQueryExecutorCollector
+     */
     @Override
     public HybridQueryExecutorCollector<LeafReaderContext, ScorerSupplier> newCollector() {
         return HybridQueryExecutorCollector.newCollector(context);
     }
 
+    /**
+     * mergeScoreSuppliers will build list of scoreSupplier from given collections.
+     * This method should be called after HybridQueryExecutorCollector's collect method is called.
+     * @param collectors List of collectors which is used to perform collection in parallel
+     * @return list of {@link ScorerSupplier}
+     */
     public List<ScorerSupplier> mergeScoreSuppliers(List<HybridQueryExecutorCollector<LeafReaderContext, ScorerSupplier>> collectors) {
         List<ScorerSupplier> scorerSuppliers = collectors.stream()
             .map(HybridQueryExecutorCollector::getResult)

src/main/java/org/opensearch/neuralsearch/query/HybridQueryScoresCollectionManager.java

@@ -11,16 +11,32 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * {@link HybridQueryScoresCollectionManager} is responsible for creating {@link HybridQueryExecutorCollector} instances.
+ * Useful to create {@link HybridQueryExecutorCollector} instances that calls score method on individual
+ * scorer
+ */
 @NoArgsConstructor
 public class HybridQueryScoresCollectionManager
     implements
         HybridQueryExecutorCollectorManager<HybridQueryExecutorCollector<?, Map.Entry<Integer, Float>>, Float> {
 
+    /**
+     * Returns new {@link HybridQueryExecutorCollector} instance to facilitate parallel execution
+     * by individual tasks
+     * @return HybridQueryExecutorCollector instance
+     */
     @Override
     public HybridQueryExecutorCollector<?, Map.Entry<Integer, Float>> newCollector() {
         return HybridQueryExecutorCollector.newCollector(null);
     }
 
+    /**
+     * Update scores from collectors that was previously collected from scorer.
+     * Collector will provide score and index of scorer to map it back to scores array.
+     * @param collectors List of scorers where we want to calculate score.
+     * @param scores Float array to combine scores from available scores
+     */
     public void updateScores(final List<HybridQueryExecutorCollector<?, Map.Entry<Integer, Float>>> collectors, final float[] scores) {
         for (HybridQueryExecutorCollector<?, Map.Entry<Integer, Float>> collector : collectors) {
             scores[collector.getResult().getKey()] = collector.getResult().getValue();