From 35f4d1f23398af8b10920fed44816eabdaa3e08e Mon Sep 17 00:00:00 2001
From: Michael Sokolov <sokolovm@amazon.com>
Date: Thu, 2 Jan 2025 14:35:13 -0500
Subject: [PATCH] comments

---
 .../misc/index/AbstractBPReorderer.java       | 17 +++++++++++++
 .../lucene/misc/index/IndexReorderer.java     | 24 +++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java
index a687eddc8d7..3f7442a2526 100644
--- a/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java
+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/AbstractBPReorderer.java
@@ -1,5 +1,22 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.apache.lucene.misc.index;
 
+/** Base class for docid-reorderers implemented using binary partitioning (BP). */
 public abstract class AbstractBPReorderer implements IndexReorderer {
   /**
    * Minimum size of partitions. The algorithm will stop recursing when reaching partitions below
diff --git a/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java b/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java
index 44e8ffe4b5f..1fdba7a4eb0 100644
--- a/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java
+++ b/lucene/misc/src/java/org/apache/lucene/misc/index/IndexReorderer.java
@@ -1,3 +1,19 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.apache.lucene.misc.index;
 
 import java.io.IOException;
@@ -6,7 +22,15 @@
 import org.apache.lucene.index.Sorter;
 import org.apache.lucene.store.Directory;
 
+/** Interface for docid-reordering expected by {@link BPReorderingMergePolicy}. */
 public interface IndexReorderer {
+  /**
+   * Returns a mapping from old to new docids.
+   *
+   * @param reader the reader whose docs are to be reordered
+   * @param tempDir temporary files may be stored here while reordering.
+   * @param executor may be used to parallelize reordering work.
+   */
   Sorter.DocMap computeDocMap(CodecReader reader, Directory tempDir, Executor executor)
       throws IOException;
 }