adding a lot of java doc

Author: normen662

fdb-extensions/src/main/java/com/apple/foundationdb/async/MoreAsyncUtil.java

@@ -1057,6 +1057,23 @@ public static CompletableFuture<Void> swallowException(@Nonnull CompletableFutur
         return result;
     }
 
+    /**
+     * Method that provides the functionality of a for loop, however, in an asynchronous way. The result of this method
+     * is a {@link CompletableFuture} that represents the result of the last iteration of the loop body.
+     * @param startI an integer analogous to the starting value of a loop variable in a for loop
+     * @param startU an object of some type {@code U} that represents some initial state that is passed to the loop's
+     *        initial state
+     * @param conditionPredicate a predicate on the loop variable that must be true before the next iteration is
+     *        entered; analogous to the condition in a for loop
+     * @param stepFunction a unary operator used for modifying the loop variable after each iteration
+     * @param body a bi-function to be called for each iteration; this function is initially invoked using
+     *        {@code startI} and {@code startU}; the result of the body is then passed into the next iterator's body
+     *        together with a new value for the loop variable. In this way callers can access state inside an iteration
+     *        that was computed in a previous iteration.
+     * @param executor the executor
+     * @param <U> the type of the result of the body {@link BiFunction}
+     * @return a {@link CompletableFuture} containing the result of the last iteration's body invocation.
+     */
     @Nonnull
     public static <U> CompletableFuture<U> forLoop(final int startI, @Nullable final U startU,
                                                    @Nonnull final IntPredicate conditionPredicate,
@@ -1079,6 +1096,18 @@ public static <U> CompletableFuture<U> forLoop(final int startI, @Nullable final
         }, executor).thenApply(ignored -> lastResultAtomic.get());
     }
 
+    /**
+     * Method to iterate over some items, for each of which a body is executed asynchronously. The result of each such
+     * executed is then collected in a list and returned as a {@link CompletableFuture} over that list.
+     * @param items the items to iterate over
+     * @param body a function to be called for each item
+     * @param parallelism the maximum degree of parallelism this method should use
+     * @param executor the executor
+     * @param <T> the type of item
+     * @param <U> the type of the result
+     * @return a {@link CompletableFuture} containing a list of results collected from the individual body invocations
+     */
+    @Nonnull
     @SuppressWarnings("unchecked")
     public static <T, U> CompletableFuture<List<U>> forEach(@Nonnull final Iterable<T> items,
                                                             @Nonnull final Function<T, CompletableFuture<U>> body,

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/BaseNeighborsChangeSet.java

@@ -1,5 +1,5 @@
 /*
- * InliningNode.java
+ * BaseNeighborsChangeSet.java
  *
  * This source file is part of the FoundationDB open source project
  *

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/CompactStorageAdapter.java

@@ -41,29 +41,81 @@
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * The {@code CompactStorageAdapter} class is a concrete implementation of {@link StorageAdapter} for managing HNSW
+ * graph data in a compact format.
+ * <p>
+ * It handles the serialization and deserialization of graph nodes to and from a persistent data store. This
+ * implementation is optimized for space efficiency by storing nodes with their accompanying vector data and by storing
+ * just neighbor primary keys. It extends {@link AbstractStorageAdapter} to inherit common storage logic.
+ */
 class CompactStorageAdapter extends AbstractStorageAdapter<NodeReference> implements StorageAdapter<NodeReference> {
     @Nonnull
     private static final Logger logger = LoggerFactory.getLogger(CompactStorageAdapter.class);
 
+    /**
+     * Constructs a new {@code CompactStorageAdapter}.
+     * <p>
+     * This constructor initializes the adapter by delegating to the superclass,
+     * setting up the necessary components for managing an HNSW graph.
+     *
+     * @param config the HNSW graph configuration, must not be null. See {@link HNSW.Config}.
+     * @param nodeFactory the factory used to create new nodes of type {@link NodeReference}, must not be null.
+     * @param subspace the {@link Subspace} where the graph data is stored, must not be null.
+     * @param onWriteListener the listener to be notified of write events, must not be null.
+     * @param onReadListener the listener to be notified of read events, must not be null.
+     */
     public CompactStorageAdapter(@Nonnull final HNSW.Config config, @Nonnull final NodeFactory<NodeReference> nodeFactory,
                                  @Nonnull final Subspace subspace,
                                  @Nonnull final OnWriteListener onWriteListener,
                                  @Nonnull final OnReadListener onReadListener) {
         super(config, nodeFactory, subspace, onWriteListener, onReadListener);
     }
 
+    /**
+     * Returns this storage adapter instance, as it is already a compact storage adapter.
+     * @return the current instance, which serves as its own compact representation.
+     *         This will never be {@code null}.
+     */
     @Nonnull
     @Override
     public StorageAdapter<NodeReference> asCompactStorageAdapter() {
         return this;
     }
 
+    /**
+     * Returns this adapter as a {@code StorageAdapter} that supports inlining.
+     * <p>
+     * This operation is not supported by a compact storage adapter. Calling this method on this implementation will
+     * always result in an {@code IllegalStateException}.
+     *
+     * @return an instance of {@code StorageAdapter} that supports inlining
+     *
+     * @throws IllegalStateException unconditionally, as this operation is not supported
+     * on a compact storage adapter.
+     */
     @Nonnull
     @Override
     public StorageAdapter<NodeReferenceWithVector> asInliningStorageAdapter() {
         throw new IllegalStateException("cannot call this method on a compact storage adapter");
     }
 
+    /**
+     * Asynchronously fetches a node from the database for a given layer and primary key.
+     * <p>
+     * This internal method constructs a raw byte key from the {@code layer} and {@code primaryKey}
+     * within the store's data subspace. It then uses the provided {@link ReadTransaction} to
+     * retrieve the raw value. If a value is found, it is deserialized into a {@link Node} object
+     * using the {@code nodeFromRaw} method.
+     *
+     * @param readTransaction the transaction to use for the read operation
+     * @param layer the layer of the node to fetch
+     * @param primaryKey the primary key of the node to fetch
+     *
+     * @return a future that will complete with the fetched {@link Node}
+     *
+     * @throws IllegalStateException if the node cannot be found in the database for the given key
+     */
     @Nonnull
     @Override
     protected CompletableFuture<Node<NodeReference>> fetchNodeInternal(@Nonnull final ReadTransaction readTransaction,
@@ -80,20 +132,52 @@ protected CompletableFuture<Node<NodeReference>> fetchNodeInternal(@Nonnull fina
                 });
     }
 
+    /**
+     * Deserializes a raw key-value byte array pair into a {@code Node}.
+     * <p>
+     * This method first converts the {@code valueBytes} into a {@link Tuple} and then,
+     * along with the {@code primaryKey}, constructs the final {@code Node} object.
+     * It also notifies any registered {@link OnReadListener} about the raw key-value
+     * read and the resulting node creation.
+     *
+     * @param layer the layer of the HNSW where this node resides
+     * @param primaryKey the primary key for the node
+     * @param keyBytes the raw byte representation of the node's key
+     * @param valueBytes the raw byte representation of the node's value, which will be deserialized
+     *
+     * @return a non-null, deserialized {@link Node} object
+     */
     @Nonnull
     private Node<NodeReference> nodeFromRaw(final int layer, final @Nonnull Tuple primaryKey,
                                             @Nonnull final byte[] keyBytes, @Nonnull final byte[] valueBytes) {
         final Tuple nodeTuple = Tuple.fromBytes(valueBytes);
-        final Node<NodeReference> node = nodeFromTuples(primaryKey, nodeTuple);
+        final Node<NodeReference> node = nodeFromKeyValuesTuples(primaryKey, nodeTuple);
         final OnReadListener onReadListener = getOnReadListener();
         onReadListener.onNodeRead(layer, node);
         onReadListener.onKeyValueRead(layer, keyBytes, valueBytes);
         return node;
     }
 
+    /**
+     * Constructs a compact {@link Node} from its representation as stored key and value tuples.
+     * <p>
+     * This method deserializes a node by extracting its components from the provided tuples. It verifies that the
+     * node is of type {@link NodeKind#COMPACT} before delegating the final construction to
+     * {@link #compactNodeFromTuples(Tuple, Tuple, Tuple)}. The {@code valueTuple} is expected to have a specific
+     * structure: the serialized node kind at index 0, a nested tuple for the vector at index 1, and a nested
+     * tuple for the neighbors at index 2.
+     *
+     * @param primaryKey the tuple representing the primary key of the node
+     * @param valueTuple the tuple containing the serialized node data, including kind, vector, and neighbors
+     *
+     * @return the reconstructed compact {@link Node}
+     *
+     * @throws com.google.common.base.VerifyException if the node kind encoded in {@code valueTuple} is not
+     *         {@link NodeKind#COMPACT}
+     */
     @Nonnull
-    private Node<NodeReference> nodeFromTuples(@Nonnull final Tuple primaryKey,
-                                               @Nonnull final Tuple valueTuple) {
+    private Node<NodeReference> nodeFromKeyValuesTuples(@Nonnull final Tuple primaryKey,
+                                                        @Nonnull final Tuple valueTuple) {
         final NodeKind nodeKind = NodeKind.fromSerializedNodeKind((byte)valueTuple.getLong(0));
         Verify.verify(nodeKind == NodeKind.COMPACT);
 
@@ -105,6 +189,21 @@ private Node<NodeReference> nodeFromTuples(@Nonnull final Tuple primaryKey,
         return compactNodeFromTuples(primaryKey, vectorTuple, neighborsTuple);
     }
 
+    /**
+     * Creates a compact in-memory representation of a graph node from its constituent storage tuples.
+     * <p>
+     * This method deserializes the raw data stored in {@code Tuple} objects into their
+     * corresponding in-memory types. It extracts the vector, constructs a list of
+     * {@link NodeReference} objects for the neighbors, and then uses a factory to
+     * assemble the final {@code Node} object.
+     * </p>
+     *
+     * @param primaryKey the tuple representing the node's primary key
+     * @param vectorTuple the tuple containing the node's vector data
+     * @param neighborsTuple the tuple containing a list of nested tuples, where each nested tuple represents a neighbor
+     *
+     * @return a new {@code Node} instance containing the deserialized data from the input tuples
+     */
     @Nonnull
     private Node<NodeReference> compactNodeFromTuples(@Nonnull final Tuple primaryKey,
                                                       @Nonnull final Tuple vectorTuple,
@@ -120,6 +219,21 @@ private Node<NodeReference> compactNodeFromTuples(@Nonnull final Tuple primaryKe
         return getNodeFactory().create(primaryKey, vector, nodeReferences);
     }
 
+    /**
+     * Writes the internal representation of a compact node to the data store within a given transaction.
+     * This method handles the serialization of the node's vector and its final set of neighbors based on the
+     * provided {@code neighborsChangeSet}.
+     *
+     * <p>The node is stored as a {@link Tuple} with the structure {@code (NodeKind, Vector, NeighborPrimaryKeys)}.
+     * The key for the storage is derived from the node's layer and its primary key. After writing, it notifies any
+     * registered write listeners via {@code onNodeWritten} and {@code onKeyValueWritten}.
+     *
+     * @param transaction the {@link Transaction} to use for the write operation.
+     * @param node the {@link Node} to be serialized and written; it is processed as a {@link CompactNode}.
+     * @param layer the graph layer index for the node, used to construct the storage key.
+     * @param neighborsChangeSet a {@link NeighborsChangeSet} containing the additions and removals, which are
+     * merged to determine the final set of neighbors to be written.
+     */
     @Override
     public void writeNodeInternal(@Nonnull final Transaction transaction, @Nonnull final Node<NodeReference> node,
                                   final int layer, @Nonnull final NeighborsChangeSet<NodeReference> neighborsChangeSet) {
@@ -151,6 +265,22 @@ public void writeNodeInternal(@Nonnull final Transaction transaction, @Nonnull f
         }
     }
 
+    /**
+     * Scans a given layer for nodes, returning an iterable over the results.
+     * <p>
+     * This method reads a limited number of nodes from a specific layer in the underlying data store.
+     * The scan can be started from a specific point using the {@code lastPrimaryKey} parameter, which is
+     * useful for paginating through the nodes in a large layer.
+     *
+     * @param readTransaction the transaction to use for reading data; must not be {@code null}
+     * @param layer the layer to scan for nodes
+     * @param lastPrimaryKey the primary key of the last node from a previous scan. If {@code null},
+     * the scan starts from the beginning of the layer.
+     * @param maxNumRead the maximum number of nodes to read in this scan
+     *
+     * @return an {@link Iterable} of {@link Node} objects found in the specified layer,
+     * limited by {@code maxNumRead}
+     */
     @Nonnull
     @Override
     public Iterable<Node<NodeReference>> scanLayer(@Nonnull final ReadTransaction readTransaction, int layer,

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/DeleteNeighborsChangeSet.java

@@ -1,5 +1,5 @@
 /*
- * InliningNode.java
+ * DeleteNeighborsChangeSet.java
  *
  * This source file is part of the FoundationDB open source project
  *

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/EntryNodeReference.java

@@ -1,5 +1,5 @@
 /*
- * NodeWithLayer.java
+ * EntryNodeReference.java
  *
  * This source file is part of the FoundationDB open source project
  *
@@ -26,18 +26,50 @@
 import javax.annotation.Nonnull;
 import java.util.Objects;
 
+/**
+ * Represents an entry reference to a node within a hierarchical graph structure.
+ * <p>
+ * This class extends {@link NodeReferenceWithVector} by adding a {@code layer}
+ * attribute. It is used to encapsulate all the necessary information for an
+ * entry point into a specific layer of the graph, including its unique identifier
+ * (primary key), its vector representation, and its hierarchical level.
+ */
 class EntryNodeReference extends NodeReferenceWithVector {
     private final int layer;
 
+    /**
+     * Constructs a new reference to an entry node.
+     * <p>
+     * This constructor initializes the node with its primary key, its associated vector,
+     * and the specific layer it belongs to within a hierarchical graph structure. It calls the
+     * superclass constructor to set the {@code primaryKey} and {@code vector}.
+     *
+     * @param primaryKey the primary key identifying the node. Must not be {@code null}.
+     * @param vector the vector data associated with the node. Must not be {@code null}.
+     * @param layer the layer number where this entry node is located.
+     */
     public EntryNodeReference(@Nonnull final Tuple primaryKey, @Nonnull final Vector<Half> vector, final int layer) {
         super(primaryKey, vector);
         this.layer = layer;
     }
 
+    /**
+     * Gets the layer value for this object.
+     * @return the integer representing the layer
+     */
     public int getLayer() {
         return layer;
     }
 
+    /**
+     * Compares this {@code EntryNodeReference} to the specified object for equality.
+     * <p>
+     * The result is {@code true} if and only if the argument is an instance of {@code EntryNodeReference}, the
+     * superclass's {@link #equals(Object)} method returns {@code true}, and the {@code layer} fields of both objects
+     * are equal.
+     * @param o the object to compare this {@code EntryNodeReference} against.
+     * @return {@code true} if the given object is equal to this one; {@code false} otherwise.
+     */
     @Override
     public boolean equals(final Object o) {
         if (!(o instanceof EntryNodeReference)) {
@@ -49,6 +81,13 @@ public boolean equals(final Object o) {
         return layer == ((EntryNodeReference)o).layer;
     }
 
+    /**
+     * Generates a hash code for this object.
+     * <p>
+     * The hash code is computed by combining the hash code of the superclass with the hash code of the {@code layer}
+     * field. This implementation is consistent with the contract of {@link Object#hashCode()}.
+     * @return a hash code value for this object.
+     */
     @Override
     public int hashCode() {
         return Objects.hash(super.hashCode(), layer);

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/HNSWHelpers.java

@@ -31,6 +31,9 @@
 public class HNSWHelpers {
     private static final char[] hexArray = "0123456789ABCDEF".toCharArray();
 
+    /**
+     * This is a utility class and is not intended to be instantiated.
+     */
     private HNSWHelpers() {
         // nothing
     }
@@ -51,11 +54,23 @@ public static String bytesToHex(byte[] bytes) {
         return "0x" + new String(hexChars).replaceFirst("^0+(?!$)", "");
     }
 
+    /**
+     * Returns a {@code Half} instance representing the specified {@code double} value, rounded to the nearest
+     * representable half-precision float value.
+     * @param d the {@code double} value to be converted.
+     * @return a non-null {@link Half} instance representing {@code d}.
+     */
     @Nonnull
     public static Half halfValueOf(final double d) {
         return Half.shortBitsToHalf(Half.halfToShortBits(Half.valueOf(d)));
     }
 
+    /**
+     * Returns a {@code Half} instance representing the specified {@code float} value, rounded to the nearest
+     * representable half-precision float value.
+     * @param f the {@code float} value to be converted.
+     * @return a non-null {@link Half} instance representing {@code f}.
+     */
     @Nonnull
     public static Half halfValueOf(final float f) {
         return Half.shortBitsToHalf(Half.halfToShortBits(Half.valueOf(f)));

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/InliningStorageAdapter.java

@@ -1,5 +1,5 @@
 /*
- * CompactStorageAdapter.java
+ * InliningStorageAdapter.java
  *
  * This source file is part of the FoundationDB open source project
  *