Merge pull request #13 from torusresearch/documentation

feat: Documentation for all public methods

ReadMe.md

@@ -12,6 +12,11 @@ If you are instead seeking the iOS implementation, please see [here](https://git
 
 2. Import the built AAR file into your application.
 
+## Building and viewing the documentation
+
+```terminal
+./gradlew javadoc && open ./tkey/build/docs/javadoc/index.html
+```
 
 ## Integration with CustomAuth
 

gradle.properties

@@ -15,6 +15,7 @@ org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
 # Android operating system, and which are packaged with your app"s APK
 # https://developer.android.com/topic/libraries/support-library/androidx-rn
 android.useAndroidX=true
+android.enableJetifier=true
 # Enables namespacing of each library's R class so that its R class includes only the
 # resources declared in the library itself and none from the library's dependencies,
 # thereby reducing the size of the R class for that library

tkey/build.gradle

@@ -5,7 +5,7 @@ plugins {
 apply plugin: 'jacoco'
 
 jacoco {
-    toolVersion = '0.8.8'
+    toolVersion = '0.8.7'
 }
 
 android {
@@ -60,11 +60,23 @@ android {
 }
 
 dependencies {
-    implementation 'androidx.appcompat:appcompat:1.5.0'
-    implementation 'com.google.android.material:material:1.8.0'
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    implementation 'com.google.android.material:material:1.9.0'
     testImplementation 'junit:junit:4.13.2'
-    testImplementation "org.jacoco:org.jacoco.agent:0.8.8"
-    testImplementation "org.jacoco:org.jacoco.report:0.8.8"
+    testImplementation 'org.jacoco:org.jacoco.agent:0.8.7'
+    testImplementation 'org.jacoco:org.jacoco.report:0.8.7'
     androidTestImplementation 'androidx.test.ext:junit:1.1.5'
     androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
+}
+
+task javadoc(type: Javadoc) {
+    failOnError(false)
+    source = android.sourceSets.main.java.srcDirs
+    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
+}
+
+afterEvaluate {
+    javadoc.classpath += files(android.libraryVariants.collect { variant ->
+        variant.javaCompileProvider.get().classpath.files
+    })
 }

tkey/src/main/java/com/web3auth/tkey/RuntimeError.java

@@ -1,8 +1,11 @@
 package com.web3auth.tkey;
 
+import androidx.annotation.NonNull;
+
 public class RuntimeError extends Throwable {
     public int code = -1;
 
+    @NonNull
     @Override
     public String toString() {
         return "RuntimeError{" +

tkey/src/main/java/com/web3auth/tkey/ThresholdKey/Common/KeyPoint.java

@@ -15,10 +15,20 @@ public final class KeyPoint {
 
     private native void jniKeyPointFree();
 
+    /**
+     * Instantiate a KeyPoint object using the underlying pointer.
+     * @param ptr The pointer to the underlying foreign function interface object.
+     */
     public KeyPoint(long ptr) {
         this.pointer = ptr;
     }
 
+    /**
+    * Compares two KeyPoint objects
+    * @param o Keypoint to compare against.
+    * @throws RuntimeException Indicates invalid parameters was used.
+    * @return boolean `true` if they are equal, `false` otherwise.
+    */
     @Override
     public boolean equals(Object o) {
         if (o == this) {
@@ -39,6 +49,12 @@ public boolean equals(Object o) {
         }
     }
 
+    /**
+     * Instantiate a KeyPoint object using X and Y co-ordinates in hexadecimal format.
+     * @param x X value of co-ordinate pair.
+     * @param y Y value of co-ordinate pair.
+     * @throws RuntimeError Indicates invalid parameters was used.
+     */
     public KeyPoint(String x, String y) throws RuntimeError {
         RuntimeError error = new RuntimeError();
         long result = jniKeyPointNew(x, y, error);
@@ -48,6 +64,11 @@ public KeyPoint(String x, String y) throws RuntimeError {
         pointer = result;
     }
 
+    /**
+     * Retrieves the X value of the co-ordinate pair.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String getX() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniKeyPointGetX(error);
@@ -57,6 +78,11 @@ public String getX() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Retrieves the Y value of the co-ordinate pair.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String getY() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniKeyPointGetY(error);
@@ -66,6 +92,12 @@ public String getY() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Gets the serialized form, should it be a valid PublicKey.
+     * @param format `"elliptic-compressed"` for the compressed form, otherwise the uncompressed form will be returned.
+     * @throws RuntimeError Indicates either the underlying pointer is invalid or the co-ordinate pair is not a valid PublicKey.
+     * @return String
+     */
     public String getAsCompressedPublicKey(String format) throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniKeyPointEncode(format, error);

tkey/src/main/java/com/web3auth/tkey/ThresholdKey/Common/PrivateKey.java

@@ -9,10 +9,19 @@ public final class PrivateKey {
     public String hex;
     final static String curveN = "fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141";
 
+    /**
+     * Instantiates a PrivateKey object from its' serialized format.
+     * @param key hexadecimal representation as String
+     */
     public PrivateKey(String key) {
         hex = key;
     }
 
+    /**
+     * Instantiates a PrivateKey object by random generation.
+     * @throws RuntimeError Only possible if curveN is passed externally.
+     * @return PrivateKey
+     */
     public static PrivateKey generate() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniGeneratePrivateKey(curveN, error);
@@ -21,6 +30,4 @@ public static PrivateKey generate() throws RuntimeError {
         }
         return new PrivateKey(result);
     }
-
-
 }

tkey/src/main/java/com/web3auth/tkey/ThresholdKey/Common/Result.java

@@ -1,5 +1,7 @@
 package com.web3auth.tkey.ThresholdKey.Common;
 
+
+@SuppressWarnings("unused") // linter doesn't check T is required with extends and produces unchecked cast warnings instead
 public abstract class Result<T> {
     private Result() {}
 

tkey/src/main/java/com/web3auth/tkey/ThresholdKey/Common/ShareStore.java

@@ -17,10 +17,19 @@ public final class ShareStore {
 
     final long pointer;
 
+    /**
+     * Instantiate a ShareStore object using the underlying pointer.
+     * @param ptr The pointer to the underlying foreign function interface object.
+     */
     public ShareStore(long ptr) {
         pointer = ptr;
     }
 
+    /**
+     * Instantiate a ShareStore object using its' corresponding json.
+     * @param json Json representation as String.
+     * @throws RuntimeError Indicates json is invalid.
+     */
     public ShareStore(String json) throws RuntimeError {
         RuntimeError error = new RuntimeError();
         long ptr = jniSharestoreFromJson(json, error);
@@ -30,6 +39,11 @@ public ShareStore(String json) throws RuntimeError {
         pointer = ptr;
     }
 
+    /**
+     * Serialize a ShareStore object  object to its' corresponding json.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String toJsonString() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniSharestoreToJson(error);
@@ -39,6 +53,11 @@ public String toJsonString() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Returns the share contained in the ShareStore object.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String share() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniShareStoreGetShare(error);
@@ -48,6 +67,11 @@ public String share() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Returns the share index contained in the ShareStore object.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String shareIndex() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniShareStoreGetShareIndex(error);
@@ -57,6 +81,11 @@ public String shareIndex() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Returns the polynomial ID contained in the ShareStore object.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String polynomialId() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniShareStoreGetPolynomialId(error);

tkey/src/main/java/com/web3auth/tkey/ThresholdKey/GenerateShareStoreResult.java

@@ -11,10 +11,19 @@ public final class GenerateShareStoreResult {
 
     final long pointer;
 
+    /**
+     * Instantiate a GenerateShareStoreResult object using the underlying pointer.
+     * @param ptr The pointer to the underlying foreign function interface object.
+     */
     public GenerateShareStoreResult(long ptr) {
         pointer = ptr;
     }
 
+    /**
+     * Returns the share index in the GenerateShareStoreResult object.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String getIndex() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String share_index = jniGenerateShareStoreResultGetShareIndex(error);
@@ -24,6 +33,12 @@ public String getIndex() throws RuntimeError {
         return share_index;
     }
 
+    /**
+     * Returns the share store map in the GenerateShareStoreResult object.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return ShareStoreMap
+     * @see ShareStoreMap
+     */
     public ShareStoreMap getShareStoreMap() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         long store_map = jniGenerateShareStoreResultGetShareStoreMap(error);

tkey/src/main/java/com/web3auth/tkey/ThresholdKey/KeyDetails.java

@@ -18,10 +18,20 @@ public final class KeyDetails {
 
     final long pointer;
 
+    /**
+     * Instantiate a KeyDetails object using the underlying pointer.
+     * @param ptr The pointer to the underlying foreign function interface object.
+     */
     public KeyDetails(long ptr) {
         pointer = ptr;
     }
 
+    /**
+     * Returns the share store map.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return ShareStoreMap
+     * @see KeyPoint
+     */
     public KeyPoint getPublicKeyPoint() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         long result = jniKeyDetailsGetPublicKeyPoint(error);
@@ -31,6 +41,11 @@ public KeyPoint getPublicKeyPoint() throws RuntimeError {
         return new KeyPoint(result);
     }
 
+    /**
+     * Returns the threshold.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return int
+     */
     public int getThreshold() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         int result = jniKeyDetailsGetThreshold(error);
@@ -40,6 +55,11 @@ public int getThreshold() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Returns the number of required shares.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return int
+     */
     public int getRequiredShares() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         int result = jniKeyDetailsGetRequiredShares(error);
@@ -49,6 +69,11 @@ public int getRequiredShares() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Returns the total shares.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return int
+     */
     public int getTotalShares() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         int result = jniKeyDetailsGetTotalShares(error);
@@ -58,6 +83,11 @@ public int getTotalShares() throws RuntimeError {
         return result;
     }
 
+    /**
+     * Returns the share descriptions.
+     * @throws RuntimeError Indicates underlying pointer is invalid.
+     * @return String
+     */
     public String getShareDescriptions() throws RuntimeError {
         RuntimeError error = new RuntimeError();
         String result = jniKeyDetailsGetShareDescriptions(error);