docs: fill in missing javadoc (#4233)

Now that the javadoc is on the website, I noticed it was pretty slim...

This was mostly Claude Code, I skimmed most of the diff and fixed a few
small nits myself.

---------

Signed-off-by: Andrew Duffy <[email protected]>

Author: a10y

java/vortex-jni/src/main/java/dev/vortex/DateTimeUtil.java

@@ -9,16 +9,42 @@
 import java.time.ZoneOffset;
 import java.time.temporal.ChronoUnit;
 
-// Helpful functions borrowed from Iceberg class with same name.
+/**
+ * Utility class for date and time conversions in Vortex.
+ *
+ * <p>This class provides helper functions for converting Java date/time objects
+ * to nanoseconds since the Unix epoch, which is the internal representation
+ * used by Vortex for temporal data.</p>
+ *
+ * <p>Helpful functions borrowed from Iceberg class with same name.</p>
+ */
 public final class DateTimeUtil {
+    /**
+     * The Unix epoch as an OffsetDateTime (1970-01-01T00:00:00Z).
+     */
     public static final OffsetDateTime EPOCH = Instant.ofEpochSecond(0).atOffset(ZoneOffset.UTC);
 
-    // Just assume timestamp is already at UTC for conversion purposes.
-    // When decoded back to LocalDateTime
+    /**
+     * Converts a LocalDateTime to nanoseconds since the Unix epoch.
+     *
+     * <p>The LocalDateTime is assumed to be in UTC timezone for conversion purposes.
+     * When decoded back to LocalDateTime, the timezone information will not be preserved.</p>
+     *
+     * @param dateTime the LocalDateTime to convert
+     * @return nanoseconds since the Unix epoch
+     */
     public static long nanosFromTimestamp(LocalDateTime dateTime) {
         return ChronoUnit.NANOS.between(EPOCH, dateTime.atOffset(ZoneOffset.UTC));
     }
 
+    /**
+     * Converts an OffsetDateTime to nanoseconds since the Unix epoch.
+     *
+     * <p>The timezone information in the OffsetDateTime is preserved during conversion.</p>
+     *
+     * @param dateTime the OffsetDateTime to convert
+     * @return nanoseconds since the Unix epoch
+     */
     public static long nanosFromTimestamptz(OffsetDateTime dateTime) {
         return ChronoUnit.NANOS.between(EPOCH, dateTime);
     }

java/vortex-jni/src/main/java/dev/vortex/api/Array.java

@@ -8,45 +8,182 @@
 import org.apache.arrow.vector.VectorSchemaRoot;
 
 public interface Array extends AutoCloseable {
+    /**
+     * Returns the number of elements in this array.
+     *
+     * @return the length of the array
+     */
     long getLen();
 
+    /**
+     * Returns the total size in bytes of this array including all buffers.
+     *
+     * @return the size in bytes
+     */
     long nbytes();
 
     /**
      * Export to an ArrowVector. The data will now be owned by the VectorSchemaRoot after this operation.
      */
     VectorSchemaRoot exportToArrow(BufferAllocator allocator, VectorSchemaRoot reuse);
 
+    /**
+     * Returns the data type of this array.
+     *
+     * @return the DType describing the logical type of this array
+     */
     DType getDataType();
 
+    /**
+     * Returns a child array at the given field index.
+     *
+     * <p>This is used for accessing fields in struct arrays or elements in list arrays.</p>
+     *
+     * @param index the field index
+     * @return the child array at the specified index
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     */
     Array getField(int index);
 
+    /**
+     * Returns a slice of this array from start (inclusive) to stop (exclusive).
+     *
+     * @param start the starting index (inclusive)
+     * @param stop the ending index (exclusive)
+     * @return a new Array containing the sliced elements
+     * @throws IndexOutOfBoundsException if start or stop are out of bounds
+     */
     Array slice(int start, int stop);
 
+    /**
+     * Returns true if the value at the given index is null.
+     *
+     * @param index the element index
+     * @return true if the value is null, false otherwise
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     */
     boolean getNull(int index);
 
+    /**
+     * Returns the total number of null values in this array.
+     *
+     * @return the null count
+     */
     int getNullCount();
 
+    /**
+     * Returns the byte value at the given index.
+     *
+     * @param index the element index
+     * @return the byte value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with byte
+     */
     byte getByte(int index);
 
+    /**
+     * Returns the short value at the given index.
+     *
+     * @param index the element index
+     * @return the short value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with short
+     */
     short getShort(int index);
 
+    /**
+     * Returns the int value at the given index.
+     *
+     * @param index the element index
+     * @return the int value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with int
+     */
     int getInt(int index);
 
+    /**
+     * Returns the long value at the given index.
+     *
+     * @param index the element index
+     * @return the long value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with long
+     */
     long getLong(int index);
 
+    /**
+     * Returns the boolean value at the given index.
+     *
+     * @param index the element index
+     * @return the boolean value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with boolean
+     */
     boolean getBool(int index);
 
+    /**
+     * Returns the float value at the given index.
+     *
+     * @param index the element index
+     * @return the float value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with float
+     */
     float getFloat(int index);
 
+    /**
+     * Returns the double value at the given index.
+     *
+     * @param index the element index
+     * @return the double value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with double
+     */
     double getDouble(int index);
 
+    /**
+     * Returns the BigDecimal value at the given index.
+     *
+     * @param index the element index
+     * @return the BigDecimal value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with decimal
+     */
     BigDecimal getBigDecimal(int index);
 
+    /**
+     * Returns the UTF-8 string value at the given index.
+     *
+     * @param index the element index
+     * @return the string value
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with string
+     */
     String getUTF8(int index);
 
+    /**
+     * Returns the UTF-8 string value at the given index as a pointer and length.
+     *
+     * <p>This is a low-level method that provides direct access to the underlying
+     * string data without copying. The pointer and length are written to the
+     * provided arrays.</p>
+     *
+     * @param index the element index
+     * @param ptr array to store the pointer (first element will be set)
+     * @param len array to store the length (first element will be set)
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with string
+     */
     void getUTF8_ptr_len(int index, long[] ptr, int[] len);
 
+    /**
+     * Returns the binary value at the given index as a byte array.
+     *
+     * @param index the element index
+     * @return the binary value as a byte array
+     * @throws IndexOutOfBoundsException if index is out of bounds
+     * @throws ClassCastException if the array type is not compatible with binary
+     */
     byte[] getBinary(int index);
 
     @Override

java/vortex-jni/src/main/java/dev/vortex/api/ArrayIterator.java

@@ -5,9 +5,65 @@
 
 import java.util.Iterator;
 
+/**
+ * An iterator interface for traversing Vortex arrays while providing type information
+ * and resource management capabilities.
+ *
+ * <p>This interface extends both {@link Iterator} and {@link AutoCloseable}, allowing
+ * for efficient iteration over array elements while ensuring proper cleanup of any
+ * underlying resources. The iterator provides access to the data type of the arrays
+ * being iterated over, which is useful for type-safe processing.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * try (ArrayIterator iterator = array.getIterator()) {
+ *     DType dataType = iterator.getDataType();
+ *     while (iterator.hasNext()) {
+ *         Array element = iterator.next();
+ *         // Process element based on dataType
+ *     }
+ * }
+ * }</pre>
+ *
+ * @see Array
+ * @see DType
+ * @see Iterator
+ * @see AutoCloseable
+ */
 public interface ArrayIterator extends AutoCloseable, Iterator<Array> {
+    /**
+     * Returns the data type of the arrays that this iterator produces.
+     *
+     * <p>This method provides type information about the arrays that will be
+     * returned by subsequent calls to {@link #next()}. The data type remains
+     * constant throughout the lifetime of the iterator and can be used for
+     * type-safe processing and validation.</p>
+     *
+     * @return the {@link DType} representing the data type of arrays produced by this iterator
+     */
     DType getDataType();
 
+    /**
+     * Closes this iterator and releases any underlying resources.
+     *
+     * <p>This method should be called when the iterator is no longer needed to
+     * ensure proper cleanup of any native resources or memory allocations.
+     * After calling this method, the iterator should not be used for further
+     * operations.</p>
+     *
+     * <p>It is recommended to use this iterator within a try-with-resources
+     * statement to ensure automatic cleanup:</p>
+     * <pre>{@code
+     * try (ArrayIterator iterator = array.getIterator()) {
+     *     // Use iterator
+     * } // close() is called automatically
+     * }</pre>
+     *
+     * <p>This method overrides {@link AutoCloseable#close()} and does not
+     * throw any checked exceptions, making it safe to use in any context.</p>
+     *
+     * @see AutoCloseable#close()
+     */
     @Override
     void close();
 }