Added javadocs for MultiFieldsInnerRetrieverUtils

Author: Mikep86

x-pack/plugin/rank-rrf/src/main/java/org/elasticsearch/xpack/rank/MultiFieldsInnerRetrieverUtils.java

@@ -19,6 +19,7 @@
 import org.elasticsearch.search.retriever.CompoundRetrieverBuilder;
 import org.elasticsearch.search.retriever.RetrieverBuilder;
 import org.elasticsearch.search.retriever.StandardRetrieverBuilder;
+import org.elasticsearch.xpack.rank.linear.LinearRetrieverBuilder;
 
 import java.util.ArrayList;
 import java.util.Collection;
@@ -32,11 +33,27 @@
 import static org.elasticsearch.action.ValidateActions.addValidationError;
 import static org.elasticsearch.index.IndexSettings.DEFAULT_FIELD_SETTING;
 
+/**
+ * A utility class for managing and validating the multi-fields query format for the {@link LinearRetrieverBuilder} retriever.
+ */
 public class MultiFieldsInnerRetrieverUtils {
     private MultiFieldsInnerRetrieverUtils() {}
 
     public record WeightedRetrieverSource(CompoundRetrieverBuilder.RetrieverSource retrieverSource, float weight) {}
 
+    /**
+     * Validates the parameters related to the multi-fields query format.
+     *
+     * @param innerRetrievers The custom inner retrievers already defined
+     * @param fields The fields to query
+     * @param query The query text
+     * @param retrieverName The containing retriever name
+     * @param retrieversParamName The parameter name for custom inner retrievers
+     * @param fieldsParamName The parameter name for the fields to query
+     * @param queryParamName The parameter name for the query text
+     * @param validationException The validation exception
+     * @return The validation exception with any multi-fields query format validation errors appended
+     */
     public static ActionRequestValidationException validateParams(
         List<CompoundRetrieverBuilder.RetrieverSource> innerRetrievers,
         List<String> fields,
@@ -86,6 +103,33 @@ public static ActionRequestValidationException validateParams(
         return validationException;
     }
 
+    /**
+     * Generate the inner retriever tree for the given fields, weights, and query. The tree follows this structure:
+     *
+     * <pre>
+     * multi_match query on all lexical fields
+     * normalizer retriever
+     *   match query on semantic_text field A
+     *   match query on semantic_text field B
+     *   ...
+     *   match query on semantic_text field Z
+     * </pre>
+     *
+     * <p>
+     * Where the normalizer retriever is constructed by the {@code innerNormalizerGenerator} function.
+     * </p>
+     * <p>
+     * This tree structure is repeated for each index in {@code indicesMetadata}. That is to say, that for each index in
+     * {@code indicesMetadata}, (up to) a pair of retrievers will be added to the returned {@code RetrieverBuilder} list.
+     * </p>
+     *
+     * @param fieldsAndWeights The fields to query and their respective weights, in "field^weight" format
+     * @param query The query text
+     * @param indicesMetadata The metadata for the indices to search
+     * @param innerNormalizerGenerator The inner normalizer retriever generator function
+     * @param weightValidator The field weight validator
+     * @return The inner retriever tree as a {@code RetrieverBuilder} list
+     */
     public static List<RetrieverBuilder> generateInnerRetrievers(
         List<String> fieldsAndWeights,
         String query,