From df1797a4305e8d5319a36b18879178402062ce4b Mon Sep 17 00:00:00 2001
From: Bryan Jacobowitz <BJACOBOWITZ1@bloomberg.net>
Date: Thu, 15 Feb 2024 15:39:48 -0500
Subject: [PATCH] Javadoc for WrappedCandidateMatcher and WrappedMatcherFactory

---
 .../monitor/WrappedCandidateMatcher.java      | 51 ++++++++++++++++++-
 .../lucene/monitor/WrappedMatcherFactory.java |  9 ++++
 2 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java
index 2d46c2544db4..c3653c76a445 100644
--- a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java
+++ b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java
@@ -22,45 +22,92 @@
 import java.util.Map;
 import org.apache.lucene.search.Query;
 
-// Wrapper class for an existing candidate matcher exposing finish, matchQuery and reportError
-// for composition of matchers
+/**
+ * Wrapper class for an existing candidate matcher exposing finish, matchQuery and reportError for
+ * composition of matchers
+ */
 public class WrappedCandidateMatcher<T extends QueryMatch> {
 
   private CandidateMatcher<T> delegateTo;
 
+  /**
+   * Creates a new WrappedCandidateMatcher delegating to the supplied CandidateMatcher
+   *
+   * @param wrapThis the CandidateMatcher to which functions should be delegate
+   */
   public WrappedCandidateMatcher(CandidateMatcher<T> wrapThis) {
     delegateTo = wrapThis;
   }
 
+  /**
+   * Runs the supplied query against the delegate CandidateMatcher's set of documents, storing any
+   * resulting match, and recording the query in the presearcher hits
+   *
+   * @param queryId the query id
+   * @param matchQuery the query to run
+   * @param metadata the query metadata
+   * @throws IOException on IO errors
+   */
   public void matchQuery(String queryId, Query matchQuery, Map<String, String> metadata)
       throws IOException {
     delegateTo.matchQuery(queryId, matchQuery, metadata);
   }
 
+  /**
+   * @return the matches from this matcher
+   */
   public MultiMatchingQueries<T> finish(long buildTime, int queryCount) {
     return delegateTo.finish(buildTime, queryCount);
   }
 
+  /**
+   * Record a match into delegate
+   *
+   * @param match a QueryMatch object
+   */
   protected void addMatch(T match, int doc) {
     delegateTo.addMatch(match, doc);
   }
 
+  /**
+   * If two matches from the same query are found (for example, two branches of a disjunction),
+   * combine them using the delegate's resolve function.
+   *
+   * @param match1 the first match found
+   * @param match2 the second match found
+   * @return a Match object that combines the two
+   */
   public T resolve(T match1, T match2) {
     return delegateTo.resolve(match1, match2);
   }
 
+  /** If running a query throws an Exception, this function will add error into delegate */
   public void reportError(String queryId, Exception e) {
     delegateTo.reportError(queryId, e);
   }
 
+  /** Called when all monitoring of a batch of documents is complete */
   protected void doFinish() {
     delegateTo.doFinish();
   }
 
+  /** Copy all matches from another CandidateMatcher */
   protected void copyMatches(CandidateMatcher<T> other) {
     delegateTo.copyMatches(other);
   }
 
+  /**
+   * Build a MultiMatchingQueries
+   *
+   * @param matches the matches to include, mapping from queryId to match
+   * @param errors any errors thrown while evaluating matches
+   * @param queryBuildTime how long (in ns) it took to build the Presearcher query for the matcher
+   *     run
+   * @param searchTime how long (in ms) it took to run the selected queries
+   * @param queriesRun the number of queries passed to this CandidateMatcher during the matcher run
+   * @param batchSize the number of documents in the batch
+   * @return a MultiMatchingQueries object with the results of matching a batch of Documents
+   */
   public static <T1 extends QueryMatch> MultiMatchingQueries<T1> buildMultiMatchingQueries(
       List<Map<String, T1>> matches,
       Map<String, Exception> errors,
diff --git a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java
index 8421409bedf6..5076be93909e 100644
--- a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java
+++ b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java
@@ -19,7 +19,16 @@
 
 import org.apache.lucene.search.IndexSearcher;
 
+/**
+ * Interface for the creation of new WrappedCandidateMatcher objects
+ *
+ * @param <T> a subclass of {@link CandidateMatcher}
+ */
 public interface WrappedMatcherFactory<T extends QueryMatch> {
 
+  /**
+   * Create a new {@link WrappedCandidateMatcher} object, to be used to select queries to match
+   * against the passed-in IndexSearcher
+   */
   WrappedCandidateMatcher<T> createWrappedMatcher(IndexSearcher searcher);
 }