From 196723af5de7a170ade6be9e35f7bc19ffcdbdb4 Mon Sep 17 00:00:00 2001
From: Simon Cooper <simon.cooper@elastic.co>
Date: Mon, 8 Dec 2025 11:26:36 +0000
Subject: [PATCH] Add module-info docs to simdvec

---
 libs/simdvec/src/main/java/module-info.java    | 18 ++++++++++++++++++
 .../simdvec/VectorScorerFactoryImpl.java       |  6 ++++++
 2 files changed, 24 insertions(+)

diff --git a/libs/simdvec/src/main/java/module-info.java b/libs/simdvec/src/main/java/module-info.java
index 44f6e39d5dbab..8cf2bac6a9504 100644
--- a/libs/simdvec/src/main/java/module-info.java
+++ b/libs/simdvec/src/main/java/module-info.java
@@ -7,6 +7,24 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
+/**
+ * Contains Panama and native SIMD implementations of various vector operations.
+ * <p>
+ * The native code is contained in C++ files, with implementations for ARM and two generations of x86,
+ * using significant amounts of CPU intrinsics to utilise specific SIMD operations.
+ * The method handles are loaded using FFI, and made available through a series
+ * of wrapper classes to be called from Elasticsearch-defined vector formats.
+ * <p>
+ * Because the APIs used to perform SIMD operations from Java
+ * and call native code changes between JVM versions,
+ * there are different implementations of the wrapper classes for different JVM versions.
+ * This is handled using multi-release jars, with the JVM-specific implementations
+ * contained in the {@code mainXX} source sets.
+ * <p>
+ * As a result, some of the implementations in the {@code main} source set are not actually
+ * called at runtime, and only exist to be compiled against. The correct implementation to use
+ * at runtime is selected by the multi-release classloader.
+ */
 module org.elasticsearch.simdvec {
     requires org.elasticsearch.nativeaccess;
     requires org.apache.lucene.core;
diff --git a/libs/simdvec/src/main/java/org/elasticsearch/simdvec/VectorScorerFactoryImpl.java b/libs/simdvec/src/main/java/org/elasticsearch/simdvec/VectorScorerFactoryImpl.java
index 6248902c32e7a..dfe376e081fba 100644
--- a/libs/simdvec/src/main/java/org/elasticsearch/simdvec/VectorScorerFactoryImpl.java
+++ b/libs/simdvec/src/main/java/org/elasticsearch/simdvec/VectorScorerFactoryImpl.java
@@ -19,6 +19,12 @@
 
 final class VectorScorerFactoryImpl implements VectorScorerFactory {
 
+    /*
+     * This class is never actually used, it only exists here to be referenced at compile time.
+     * The actual implementation is loaded from main21 or main22, depending on JVM version,
+     * by the multi-release jar set up by the MrjarPlugin during build time.
+     */
+
     static final VectorScorerFactoryImpl INSTANCE = null;
 
     @Override