javadoc for base [graph] (#548)

* javadoc backfill for jvector_base [graph]
* expanded scope of change to include access modifiers and verbiage

Author: jshook

jvector-base/src/main/java/io/github/jbellis/jvector/graph/disk/AbstractGraphIndexWriter.java

@@ -38,11 +38,19 @@
 import java.util.function.IntFunction;
 import java.util.stream.Collectors;
 
+/**
+ * Abstract base class for writing graph indexes to disk.
+ * @param <T> the type of the output writer
+ */
 public abstract class AbstractGraphIndexWriter<T extends IndexWriter> implements  GraphIndexWriter {
-    public static final int FOOTER_MAGIC = 0x4a564244; // "EOF magic"
-    public static final int FOOTER_OFFSET_SIZE = Long.BYTES; // The size of the offset in the footer
-    public static final int FOOTER_MAGIC_SIZE = Integer.BYTES; // The size of the magic number in the footer
-    public static final int FOOTER_SIZE = FOOTER_MAGIC_SIZE + FOOTER_OFFSET_SIZE; // The total size of the footer
+    /** A magic number to indicate the file footer */
+    public static final int FOOTER_MAGIC = 0x4a564244;
+    /** The size of the offset in the footer. */
+    public static final int FOOTER_OFFSET_SIZE = Long.BYTES;
+    /** The size of the magic number in the footer. */
+    public static final int FOOTER_MAGIC_SIZE = Integer.BYTES;
+    /** The total size of the footer. */
+    public static final int FOOTER_SIZE = FOOTER_MAGIC_SIZE + FOOTER_OFFSET_SIZE;
     final int version;
     final ImmutableGraphIndex graph;
     final OrdinalMapper ordinalMapper;
@@ -99,12 +107,17 @@ public abstract class AbstractGraphIndexWriter<T extends IndexWriter> implements
     }
 
     /**
+     * Gets the maximum ordinal written so far.
      * @return the maximum ordinal written so far, or -1 if no ordinals have been written yet
      */
     public int getMaxOrdinal() {
         return maxOrdinalWritten;
     }
 
+    /**
+     * Gets the set of features.
+     * @return the feature set
+     */
     public Set<FeatureId> getFeatureSet() {
         return featureMap.keySet();
     }
@@ -123,6 +136,8 @@ boolean isSeparated(Feature feature) {
     }
 
     /**
+     * Computes sequential renumbering for graph ordinals.
+     * @param graph the graph index to renumber
      * @return a Map of old to new graph ordinals where the new ordinals are sequential starting at 0,
      * while preserving the original relative ordering in `graph`.  That is, for all node ids i and j,
      * if i &lt; j in `graph` then map[i] &lt; map[j] in the returned map.  "Holes" left by
@@ -174,11 +189,11 @@ void writeFooter(ImmutableGraphIndex.View view, long headerOffset) throws IOExce
     /**
      * Writes the index header, including the graph size, so that OnDiskGraphIndex can open it.
      * The output IS flushed.
-     * <p>
-     * Public so that you can write the index size (and thus usefully open an OnDiskGraphIndex against the index)
-     * to read Features from it before writing the edges.
+     * @param view the graph index view
+     * @param startOffset the start offset
+     * @throws IOException if an I/O error occurs
      */
-    public synchronized void writeHeader(ImmutableGraphIndex.View view, long startOffset) throws IOException {
+    protected synchronized void writeHeader(ImmutableGraphIndex.View view, long startOffset) throws IOException {
         // graph-level properties
         var layerInfo = CommonHeader.LayerInfo.fromGraph(graph, ordinalMapper);
         var commonHeader = new CommonHeader(version,
@@ -302,6 +317,8 @@ void writeSeparatedFeatures(Map<FeatureId, IntFunction<Feature.State>> featureSt
      * <p>
      * K - the type of the writer to build
      * T - the type of the output stream
+     * @param <K> the type of the writer to build
+     * @param <T> the type of the output stream
      */
     public abstract static class Builder<K extends AbstractGraphIndexWriter<T>, T extends IndexWriter> {
         final ImmutableGraphIndex graphIndex;
@@ -310,13 +327,23 @@ public abstract static class Builder<K extends AbstractGraphIndexWriter<T>, T ex
         OrdinalMapper ordinalMapper;
         int version;
 
+        /**
+         * Constructs a Builder.
+         * @param graphIndex the graph index
+         * @param out the output writer
+         */
         public Builder(ImmutableGraphIndex graphIndex, T out) {
             this.graphIndex = graphIndex;
             this.out = out;
             this.features = new EnumMap<>(FeatureId.class);
             this.version = OnDiskGraphIndex.CURRENT_VERSION;
         }
 
+        /**
+         * Sets the version.
+         * @param version the version
+         * @return this builder
+         */
         public Builder<K, T> withVersion(int version) {
             if (version > OnDiskGraphIndex.CURRENT_VERSION) {
                 throw new IllegalArgumentException("Unsupported version: " + version);
@@ -326,16 +353,31 @@ public Builder<K, T> withVersion(int version) {
             return this;
         }
 
+        /**
+         * Adds a feature.
+         * @param feature the feature
+         * @return this builder
+         */
         public Builder<K, T> with(Feature feature) {
             features.put(feature.id(), feature);
             return this;
         }
 
+        /**
+         * Sets the ordinal mapper.
+         * @param ordinalMapper the ordinal mapper
+         * @return this builder
+         */
         public Builder<K, T> withMapper(OrdinalMapper ordinalMapper) {
             this.ordinalMapper = ordinalMapper;
             return this;
         }
 
+        /**
+         * Builds the writer.
+         * @return the writer
+         * @throws IOException if an I/O error occurs
+         */
         public K build() throws IOException {
             if (version < 3 && (!features.containsKey(FeatureId.INLINE_VECTORS) || features.size() > 1)) {
                 throw new IllegalArgumentException("Only INLINE_VECTORS is supported until version 3");
@@ -360,12 +402,28 @@ public K build() throws IOException {
             return reallyBuild(dimension);
         }
 
+        /**
+         * Actually builds the writer with the given dimension.
+         * @param dimension the dimension
+         * @return the writer
+         * @throws IOException if an I/O error occurs
+         */
         protected abstract K reallyBuild(int dimension) throws IOException;
 
+        /**
+         * Sets the ordinal mapping.
+         * @param oldToNewOrdinals the old to new ordinals map
+         * @return this builder
+         */
         public Builder<K, T> withMap(Map<Integer, Integer> oldToNewOrdinals) {
             return withMapper(new OrdinalMapper.MapMapper(oldToNewOrdinals));
         }
 
+        /**
+         * Gets a feature by ID.
+         * @param featureId the feature ID
+         * @return the feature
+         */
         public Feature getFeature(FeatureId featureId) {
             return features.get(featureId);
         }

jvector-base/src/main/java/io/github/jbellis/jvector/graph/disk/GraphIndexWriter.java

@@ -36,6 +36,7 @@ public interface GraphIndexWriter extends Closeable {
      * Each supplier takes a node ordinal and returns a FeatureState suitable for Feature.writeInline.
      *
      * @param featureStateSuppliers a map of FeatureId to a function that returns a Feature.State
+     * @throws IOException if an I/O error occurs
      */
     void write(Map<FeatureId, IntFunction<Feature.State>> featureStateSuppliers) throws IOException;
 }