[Java bindings] Improve javadoc + update dependencies (#213)

bindings/java/build.gradle

@@ -1,8 +1,8 @@
 plugins {
     id "application"
     id "java-test-fixtures"
-    id "me.champeau.jmh" version "0.6.8"
-    id "com.diffplug.spotless" version "6.15.0"
+    id "me.champeau.jmh" version "0.7.0"
+    id "com.diffplug.spotless" version "6.17.0"
 }
 
 repositories {
@@ -27,6 +27,16 @@ dependencies {
     testFixturesImplementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:${jacksonVersion}")
 }
 
+javadoc {
+    options.addStringOption("Xdoclint:all,-missing", "-quiet")
+}
+
+check {
+    dependsOn {
+        javadoc
+    }
+}
+
 spotless {
     java {
         googleJavaFormat()

bindings/java/c_kzg_4844_jni.c

@@ -30,8 +30,8 @@ void throw_c_kzg_exception(JNIEnv *env, C_KZG_RET error_code, const char *messag
 {
   jclass exception_class = (*env)->FindClass(env, "ethereum/ckzg4844/CKZGException");
   jstring error_message = (*env)->NewStringUTF(env, message);
-  jmethodID exception_init = (*env)->GetMethodID(env, exception_class, "<init>", "(ILjava/lang/String;)V");
-  jobject exception = (*env)->NewObject(env, exception_class, exception_init, error_code, error_message);
+  jmethodID exception_constructor = (*env)->GetMethodID(env, exception_class, "<init>", "(ILjava/lang/String;)V");
+  jobject exception = (*env)->NewObject(env, exception_class, exception_constructor, error_code, error_message);
   (*env)->Throw(env, exception);
 }
 
@@ -230,24 +230,24 @@ JNIEXPORT jobject JNICALL Java_ethereum_ckzg4844_CKZG4844JNI_computeKzgProof(JNI
     return NULL;
   }
 
-  jclass tuple_class = (*env)->FindClass(env, "ethereum/ckzg4844/Tuple");
+  jclass tuple_class = (*env)->FindClass(env, "ethereum/ckzg4844/ByteArrayTuple");
   if (tuple_class == NULL)
   {
-    throw_exception(env, "Failed to find Tuple class.");
+    throw_exception(env, "Failed to find ByteArrayTuple class.");
     return NULL;
   }
 
   jmethodID tuple_constructor = (*env)->GetMethodID(env, tuple_class, "<init>", "([B[B)V");
   if (tuple_constructor == NULL)
   {
-    throw_exception(env, "Failed to find Tuple constructor.");
+    throw_exception(env, "Failed to find ByteArrayTuple constructor.");
     return NULL;
   }
 
   jobject tuple = (*env)->NewObject(env, tuple_class, tuple_constructor, proof, y);
   if (tuple == NULL)
   {
-    throw_exception(env, "Failed to instantiate new Tuple.");
+    throw_exception(env, "Failed to instantiate new ByteArrayTuple.");
     return NULL;
   }
 

bindings/java/gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-bin.zip
+networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

bindings/java/gradlew

@@ -55,7 +55,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -80,10 +80,10 @@ do
     esac
 done
 
-APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
-
-APP_NAME="Gradle"
+# This is normally unused
+# shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
+APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
 
 # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
 DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
@@ -143,12 +143,16 @@ fi
 if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
     case $MAX_FD in #(
       max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC3045 
         MAX_FD=$( ulimit -H -n ) ||
             warn "Could not query maximum file descriptor limit"
     esac
     case $MAX_FD in  #(
       '' | soft) :;; #(
       *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC3045 
         ulimit -n "$MAX_FD" ||
             warn "Could not set maximum file descriptor limit to $MAX_FD"
     esac

bindings/java/gradlew.bat

@@ -26,6 +26,7 @@ if "%OS%"=="Windows_NT" setlocal
 
 set DIRNAME=%~dp0
 if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 

bindings/java/src/jmh/java/ethereum/ckzg4844/CKZG4844JNIBenchmark.java

@@ -125,7 +125,7 @@ public class CKZG4844JNIBenchmark {
   }
 
   @Benchmark
-  public Tuple computeKzgProof(final ComputeKzgProofState state) {
+  public ByteArrayTuple computeKzgProof(final ComputeKzgProofState state) {
     return CKZG4844JNI.computeKzgProof(state.blob, state.z);
   }
 

bindings/java/src/main/java/ethereum/ckzg4844/ByteArrayTuple.java

@@ -1,10 +1,11 @@
 package ethereum.ckzg4844;
 
-public class Tuple {
+/** A tuple holding 2 byte arrays. */
+public class ByteArrayTuple {
   private final byte[] first;
   private final byte[] second;
 
-  public Tuple(byte[] first, byte[] second) {
+  public ByteArrayTuple(byte[] first, byte[] second) {
     this.first = first;
     this.second = second;
   }
@@ -17,7 +18,7 @@ public class Tuple {
     return second;
   }
 
-  public static Tuple of(byte[] first, byte[] second) {
-    return new Tuple(first, second);
+  public static ByteArrayTuple of(byte[] first, byte[] second) {
+    return new ByteArrayTuple(first, second);
   }
 }

bindings/java/src/main/java/ethereum/ckzg4844/CKZG4844JNI.java

@@ -63,11 +63,15 @@ public class CKZG4844JNI {
     }
   }
 
+  /** Scalar field modulus of BLS12-381 */
   public static final BigInteger BLS_MODULUS =
       new BigInteger(
           "52435875175126190479447740508185965837690552500527637822603658699938581184513");
+  /** The number of bytes in a KZG commitment */
   public static final int BYTES_PER_COMMITMENT = 48;
+  /** The number of bytes in a KZG proof */
   public static final int BYTES_PER_PROOF = 48;
+  /** Bytes used to encode a BLS scalar field element */
   public static final int BYTES_PER_FIELD_ELEMENT = 32;
 
   private CKZG4844JNI() {}
@@ -117,6 +121,7 @@ public class CKZG4844JNI {
    *
    * @param resource the resource name that contains the trusted setup
    * @param clazz the class to use to get the resource
+   * @param <T> the type of the class
    * @throws CKZGException if there is a crypto error
    * @throws IllegalArgumentException if the resource does not exist
    */
@@ -156,10 +161,10 @@ public class CKZG4844JNI {
    *
    * @param blob blob bytes
    * @param z_bytes a point
-   * @return a tuple of the proof and the value y = f(z)
+   * @return an instance of {@link ByteArrayTuple} holding the proof and the value y = f(z)
    * @throws CKZGException if there is a crypto error
    */
-  public static native Tuple computeKzgProof(byte[] blob, byte[] z_bytes);
+  public static native ByteArrayTuple computeKzgProof(byte[] blob, byte[] z_bytes);
 
   /**
    * Given a blob, return the KZG proof that is used to verify it against the commitment
@@ -203,6 +208,7 @@ public class CKZG4844JNI {
    * @param blobs flattened blobs bytes
    * @param commitments_bytes flattened commitments bytes
    * @param proofs_bytes flattened proofs bytes
+   * @param count the number of blobs (should be same as the number of proofs and commitments)
    * @return true if the proof is valid and false otherwise
    * @throws CKZGException if there is a crypto error
    */

bindings/java/src/test/java/ethereum/ckzg4844/CKZG4844JNITest.java

@@ -70,7 +70,8 @@ public class CKZG4844JNITest {
     if (PRESET != Preset.MAINNET) return;
 
     try {
-      Tuple tuple = CKZG4844JNI.computeKzgProof(test.getInput().getBlob(), test.getInput().getZ());
+      ByteArrayTuple tuple =
+          CKZG4844JNI.computeKzgProof(test.getInput().getBlob(), test.getInput().getZ());
       assertArrayEquals(test.getOutput().getFirst(), tuple.getFirst());
       assertArrayEquals(test.getOutput().getSecond(), tuple.getSecond());
     } catch (CKZGException ex) {
@@ -191,7 +192,7 @@ public class CKZG4844JNITest {
     loadTrustedSetup();
     final byte[] blob = TestUtils.createRandomBlob();
     final byte[] z_bytes = TestUtils.randomBLSFieldElementBytes();
-    final Tuple tuple = CKZG4844JNI.computeKzgProof(blob, z_bytes);
+    final ByteArrayTuple tuple = CKZG4844JNI.computeKzgProof(blob, z_bytes);
     assertEquals(CKZG4844JNI.BYTES_PER_PROOF, tuple.getFirst().length);
     assertEquals(CKZG4844JNI.BYTES_PER_FIELD_ELEMENT, tuple.getSecond().length);
     CKZG4844JNI.freeTrustedSetup();
@@ -278,8 +279,7 @@ public class CKZG4844JNITest {
 
     assertEquals(C_KZG_BADARGS, exception.getError());
     assertEquals(
-        String.format("Invalid commitment size. Expected 48 bytes but got 49."),
-        exception.getErrorMessage());
+        "Invalid commitment size. Expected 48 bytes but got 49.", exception.getErrorMessage());
 
     exception =
         assertThrows(

bindings/java/src/testFixtures/java/ethereum/ckzg4844/test_formats/ComputeKzgProofTest.java

@@ -1,6 +1,6 @@
 package ethereum.ckzg4844.test_formats;
 
-import ethereum.ckzg4844.Tuple;
+import ethereum.ckzg4844.ByteArrayTuple;
 import java.util.List;
 import org.apache.tuweni.bytes.Bytes;
 
@@ -25,12 +25,12 @@ public class ComputeKzgProofTest {
     return input;
   }
 
-  public Tuple getOutput() {
+  public ByteArrayTuple getOutput() {
     if (output == null) {
       return null;
     }
     byte[] proof = Bytes.fromHexString(output.get(0)).toArray();
     byte[] y = Bytes.fromHexString(output.get(1)).toArray();
-    return Tuple.of(proof, y);
+    return ByteArrayTuple.of(proof, y);
   }
 }