Add some introductory docs to simdvec

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;

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