CORE-11273 Add missing Javadocs to crypto APIs (#1116)

* Adds missing Javadocs to crypto APIs

* Minor amendments to existing crypto APIs Javadocs

---------

Co-authored-by: Amie Grace <[email protected]>

crypto/src/main/java/net/corda/v5/crypto/CompositeKeyNodeAndWeight.java

@@ -4,7 +4,6 @@
 
 import java.security.PublicKey;
 
-
 /**
  * A simple data class for passing keys and weights into <code>CompositeKeyGenerator</code>.
  */
@@ -13,7 +12,8 @@ public final class CompositeKeyNodeAndWeight {
     private final int weight;
 
     /**
-     * Construct a key.
+     * Creates a new {@code CompositeKeyNodeAndWeight} for
+     * the specified key and weight for the key.
      *
      * @param node   A public key.
      * @param weight The weight for that key, must be greater than zero.
@@ -25,15 +25,27 @@ public CompositeKeyNodeAndWeight(@NotNull PublicKey node, int weight) {
         this.weight = weight;
     }
 
+    /**
+     * Creates a new {@code CompositeKeyNodeAndWeight} for
+     * the specified key, defaulting the key's weight to 1.
+     *
+     * @param node  A public key.
+     */
     public CompositeKeyNodeAndWeight(@NotNull PublicKey node) {
         this(node, 1);
     }
 
+    /**
+     * @return The key of the {@code CompositeKeyNodeAndWeight}.
+     */
     @NotNull
     public PublicKey getNode() {
         return this.node;
     }
 
+    /**
+     * @return The weight of the key.
+     */
     public int getWeight() {
         return this.weight;
     }

crypto/src/main/java/net/corda/v5/crypto/CordaOID.java

@@ -7,9 +7,7 @@
  * If an OID is incorrectly assigned, it should be marked deprecated and NEVER be reused again.
  */
 public final class CordaOID {
-    private CordaOID() {
-        // this class is never constructed; it exists for the static strings only
-    }
+    private CordaOID() {}
 
     /**
      * An OID root assigned to R3, see

crypto/src/main/java/net/corda/v5/crypto/DigitalSignature.java

@@ -11,6 +11,9 @@
 @CordaSerializable
 public interface DigitalSignature {
 
+    /**
+     * @return The digital signature bytes.
+     */
     @NotNull
     byte[] getBytes();
 

crypto/src/main/java/net/corda/v5/crypto/KeySchemeCodes.java

@@ -2,6 +2,9 @@
 
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Key schemes used in Corda for signing and key derivation.
+ */
 public final class KeySchemeCodes {
     private KeySchemeCodes() {}
 

crypto/src/main/java/net/corda/v5/crypto/KeyUtils.java

@@ -6,11 +6,12 @@
 import java.util.Collections;
 import java.util.Set;
 
+/**
+ * Helper functions for key look up in a set of keys. These functions also work when the key to look up in the
+ * set of keys is {@link CompositeKey}.
+ */
 public final class KeyUtils {
-
-    private KeyUtils() {
-        // this class is never constructed; it exists for the static methods and data only
-    }
+    private KeyUtils() {}
 
     /**
      * Checks whether <code>key</code> has any intersection with the keys in <code>otherKeys</code>, 
@@ -21,15 +22,15 @@ private KeyUtils() {
      * second argument. If <code>key</code> is a compound key, the outcome is whether any of its leaf keys
      * are in <code>otherKeys</code>.
      * {@link PublicKey}.
-     *
+     * <p/>
      * This function checks against compound key tree leaves, which by definition are not {@link CompositeKey}.
      * That is why if any of the <code>otherKeys</code> is a {@link CompositeKey}, this function will not 
      * find a match, though composite keys in the <code>otherKeys</code> set is not regarded as an error; they
      * are silently ignored.
      * <p/>
      * The notion of a key being in a set is about equality, which is not the same as whether one key is 
      * fulfilled by another key. For example, a {@link CompositeKey} C could be defined to have threshold 2 and:
-     * </p>
+     * <p/>
      * <ul>
      *     <li> Public key X with weight 1 </li>
      *     <li> Public key Y with weight 1 </li>
@@ -38,8 +39,8 @@ private KeyUtils() {
      * Then we would find that <code>isKeyInSet(C, X)</code> is true, but X would not fulfill C since C is fulfilled by
      * X and Y together but not X on its. However, <code>isKeyInSet(C, Z)</code> is true, and Z fulfills C by itself.
      * 
-     * @param key       The key being checked for.
-     * @param otherKeys An {@link Iterable} sequence of {@link PublicKey}.
+     * @param key       The key being looked for.
+     * @param otherKeys The keys searched for the {@code key}.
      * @return True if <code>key</code> is in otherKeys.
      */
     public static boolean isKeyInSet(@NotNull PublicKey key, @NotNull Set<PublicKey> otherKeys) {
@@ -71,8 +72,8 @@ public static boolean isKeyInSet(@NotNull PublicKey key, @NotNull Set<PublicKey>
      * check fulfilment against a set of keys, without having to handle simple and composite keys separately (that is, this is
      * polymorphic).
      * 
-     * @param key  The key with the requirements.
-     * @param otherKeys The key to check whether requirements are fulfilled.
+     * @param key  The key to be checked whether it is being fulfilled by {@code otherKeys}.
+     * @param otherKeys The keys against which the {@code key} is being checked for fulfilment.
      */
     public static boolean isKeyFulfilledBy(@NotNull PublicKey key, @NotNull Set<PublicKey> otherKeys) {
         if (key instanceof CompositeKey) {
@@ -86,12 +87,12 @@ public static boolean isKeyFulfilledBy(@NotNull PublicKey key, @NotNull Set<Publ
      * Return true if one key fulfills the requirements of another key. See the previous variant; this overload
      * is the same as calling as the variant that takes an iterable set of other keys with <code>otherKey<code>
      * as a single element iterable. 
-     * 
+     * <p>
      * Since we do not define composite keys as acceptable on the second argument of this function, this relation
      * is not reflexive, not symmetric and not transitive. 
      *
-     * @param key The key with the requirements.
-     * @param otherKey The key to check whether requirements are fulfilled.
+     * @param key The key to be checked whether it is being fulfilled by {@code otherKey}.
+     * @param otherKey The key against which the {@code key} is being checked for fulfilment.
      */
     public static boolean isKeyFulfilledBy(@NotNull PublicKey key, @NotNull PublicKey otherKey) {
         return isKeyFulfilledBy(key,

crypto/src/main/java/net/corda/v5/crypto/MessageAuthenticationCode.java

@@ -3,11 +3,9 @@
 import org.jetbrains.annotations.NotNull;
 
 public final class MessageAuthenticationCode {
-    private MessageAuthenticationCode() {
-        // Not constructed; this class only exists to make the string constants available 
-    }
+    private MessageAuthenticationCode() {}
 
-    /*
+    /**
      * Constant specifying the HMAC SHA-256 algorithm.
      */
     @NotNull

crypto/src/main/java/net/corda/v5/crypto/SignatureSpec.java

@@ -1,6 +1,5 @@
 package net.corda.v5.crypto;
 
-
 import net.corda.v5.base.annotations.CordaSerializable;
 import net.corda.v5.base.annotations.DoNotImplement;
 import org.jetbrains.annotations.NotNull;

crypto/src/main/java/net/corda/v5/crypto/merkle/HashDigestConstants.java

@@ -6,9 +6,7 @@
  * An implementation of RFC6962 compatible merkle tree.
  */
 public final class HashDigestConstants {
-    private HashDigestConstants() {
-        // No construction allowed; this class exists to contain its static string properties. 
-    }
+    private HashDigestConstants() {}
 
     @NotNull
     public static final String HASH_DIGEST_PROVIDER_DEFAULT_NAME = "DefaultHashDigestProvider";

crypto/src/main/java/net/corda/v5/crypto/merkle/MerkleProof.java

@@ -20,17 +20,25 @@
 public interface MerkleProof {
 
     /**
-     * Get the type of the proof.
-     *
-     * @return Type of the proof.
+     * Returns the type of the proof.
      */
     @NotNull
     MerkleProofType getProofType();
 
+    /**
+     * Returns the size of the {@link MerkleTree} out of which this proof was created.
+     */
     int getTreeSize();
 
+    /**
+     * Returns disclosed plain data of a {@link MerkleTree} which are to be verified that
+     * they are indeed part of a {@code MerkleTree}.
+     */
     List<IndexedMerkleLeaf> getLeaves();
 
+    /**
+     * Returns the hashed intermediate node data supplementing the plain data.
+     */
     List<SecureHash> getHashes();
 
     /**