Merge pull request #95 from borisrizov-zf/fix/missing-javadoc

chore: fix missing and broken documentation comments

src/main/java/org/eclipse/tractusx/ssi/examples/VC.java

@@ -118,13 +118,10 @@ public static VerifiableCredential createVCWithED25519Proof(
    * @param privateKey the private key
    * @param issuer the issuer
    * @return the verifiable credential
-   * @throws UnsupportedSignatureTypeException the unsupported signature type exception <<<<<<< HEAD
-   * @throws SsiException the ssi exception
-   * @throws InvalidPrivateKeyFormatException the invalide private key format =======
-   * @throws SignatureGenerateFailedException the signature generation failed
+   * @throws UnsupportedSignatureTypeException is throws if the signature type is unsupported
    * @throws InvalidPrivateKeyFormatException the invalid private key format
-   * @throws TransformJsonLdException the json-ld transform error >>>>>>> ec99f9d (chroe: typos,
-   *     code refactor and class files removed)
+   * @throws SignatureGenerateFailedException the signature generation failed
+   * @throws TransformJsonLdException the json-ld transform error
    */
   public static VerifiableCredential createVCWithJWSProof(
       VerifiableCredential credential, IPrivateKey privateKey, Did issuer)

src/main/java/org/eclipse/tractusx/ssi/lib/crypt/x25519/X25519PrivateKey.java

@@ -59,12 +59,8 @@ public X25519PrivateKey(byte[] privateKey) throws InvalidPrivateKeyFormatExcepti
    * Instantiates a new X 25519 private key.
    *
    * @param privateKey the private key
-   * @param pemFormat the pem format <<<<<<<
-   *     HEAD:src/main/java/org/eclipse/tractusx/ssi/lib/crypt/x25519/x25519PrivateKey.java
-   * @throws InvalidPrivateKeyFormatException the invalide private key format =======
-   * @throws InvalidPrivateKeyFormatException the invalid private key format >>>>>>> 23fcfb3 (fix:
-   *     sonar
-   *     findings):src/main/java/org/eclipse/tractusx/ssi/lib/crypt/x25519/X25519PrivateKey.java
+   * @param pemFormat describes if the privateKey is in PEM format
+   * @throws InvalidPrivateKeyFormatException the invalide private key format
    */
   public X25519PrivateKey(String privateKey, boolean pemFormat)
       throws InvalidPrivateKeyFormatException {
@@ -90,6 +86,12 @@ public X25519PrivateKey(String privateKey, boolean pemFormat)
     }
   }
 
+  /**
+   * Return the private key as a string for storing in a database
+   *
+   * @return the string representation of the private key
+   * @throws KeyTransformationException is thrown if the key cannot be transformed into a string
+   */
   @Override
   public String asStringForStoring() throws KeyTransformationException {
 

src/main/java/org/eclipse/tractusx/ssi/lib/crypt/x25519/X25519PublicKey.java

@@ -45,12 +45,8 @@ public class X25519PublicKey implements IPublicKey {
   /**
    * Instantiates a new X 25519 public key.
    *
-   * @param publicKey the public key <<<<<<<
-   *     HEAD:src/main/java/org/eclipse/tractusx/ssi/lib/crypt/x25519/x25519PublicKey.java
-   * @throws InvalidPublicKeyFormatException the invalide public key format =======
-   * @throws InvalidPublicKeyFormatException the invalid public key format >>>>>>> 23fcfb3 (fix:
-   *     sonar
-   *     findings):src/main/java/org/eclipse/tractusx/ssi/lib/crypt/x25519/X25519PublicKey.java
+   * @param publicKey the public key
+   * @throws InvalidPublicKeyFormatException the invalide public key format
    */
   public X25519PublicKey(byte[] publicKey) throws InvalidPublicKeyFormatException {
     if (this.getKeyLength() != publicKey.length) {
@@ -63,7 +59,7 @@ public X25519PublicKey(byte[] publicKey) throws InvalidPublicKeyFormatException
    * Instantiates a new X25519 public key.
    *
    * @param publicKey the public key
-   * @param pemFormat the pe mformat
+   * @param pemFormat describes if the public key is PEM encoded
    * @throws InvalidPublicKeyFormatException the invalid public key format
    * @throws IOException the io exception
    */

src/main/java/org/eclipse/tractusx/ssi/lib/did/resolver/DidResolver.java

@@ -36,7 +36,7 @@ public interface DidResolver {
    * @return the resolved DID document or <em>null</em> if the provided {@code did} could not be
    *     resolved
    * @throws DidResolverException if the DID is invalid or cannot be resolved to a DID document
-   * @throws DidParseException
+   * @throws DidParseException is thrown if the DID cannot be parsed
    */
   DidDocument resolve(Did did) throws DidResolverException, DidParseException;
 

src/main/java/org/eclipse/tractusx/ssi/lib/did/web/util/Ed25519PublicKeyParser.java

@@ -41,7 +41,7 @@ private Ed25519PublicKeyParser() {
    *
    * @param publicKey the public key
    * @return public key as multibase string
-   * @throws InvalidPublicKeyFormatException
+   * @throws InvalidPublicKeyFormatException is thrown if the public key is in an unknown format
    */
   public static MultibaseString parsePublicKey(String publicKey)
       throws InvalidPublicKeyFormatException {

src/main/java/org/eclipse/tractusx/ssi/lib/exception/key/KeyTransformationException.java

@@ -23,6 +23,7 @@
 
 import org.eclipse.tractusx.ssi.lib.exception.SSIException;
 
+/** An exception thrown if a cryptographic key cannot be transformed to another format. */
 public class KeyTransformationException extends SSIException {
 
   private static final long serialVersionUID = 1L;

src/main/java/org/eclipse/tractusx/ssi/lib/jwt/SignedJwtFactory.java

@@ -48,6 +48,11 @@ public class SignedJwtFactory {
 
   private final OctetKeyPairFactory octetKeyPairFactory;
 
+  /**
+   * The public constructor
+   *
+   * @param octetKeyPairFactory a valid OKP factory
+   */
   public SignedJwtFactory(OctetKeyPairFactory octetKeyPairFactory) {
     this.octetKeyPairFactory = Objects.requireNonNull(octetKeyPairFactory);
   }
@@ -56,12 +61,12 @@ public SignedJwtFactory(OctetKeyPairFactory octetKeyPairFactory) {
    * Creates a signed JWT {@link SignedJWT} that contains a set of claims and an issuer with a
    * default configuration (60 second expiration time) {@link JwtConfig} for VP
    *
-   * @param didIssuer
-   * @param audience
-   * @param serializedPresentation
-   * @param privateKey
-   * @param keyId
-   * @return
+   * @param didIssuer the DID from the 'iss' claim
+   * @param audience the value in the 'aud' claim
+   * @param serializedPresentation a serialized VP
+   * @param privateKey a private key (format unspecified)
+   * @param keyId the id of the private key
+   * @return a signed JWT
    */
   @SneakyThrows
   public SignedJWT create(
@@ -78,13 +83,13 @@ public SignedJWT create(
    * Creates a signed JWT {@link SignedJWT} that contains a set of claims and an issuer with a
    * specific configuration {@link JwtConfig} for VP
    *
-   * @param didIssuer
-   * @param audience
-   * @param serializedPresentation
-   * @param privateKey
-   * @param keyId
-   * @param config
-   * @return
+   * @param didIssuer the DID from the 'iss' claim
+   * @param audience the value in the 'aud' claim
+   * @param serializedPresentation a serialized VP
+   * @param privateKey a private key (format unspecified)
+   * @param keyId the id of the private key
+   * @param config a JWT creation configuration
+   * @return a signed JWT
    */
   @SneakyThrows
   public SignedJWT create(
@@ -125,12 +130,12 @@ public SignedJWT create(
   /**
    * Creates a signed JWT {@link SignedJWT} from a Verifiable Credential
    *
-   * @param didIssuer
-   * @param holderIssuer
-   * @param vc
-   * @param privateKey
-   * @param keyId
-   * @return
+   * @param didIssuer the DID from the 'iss' claim
+   * @param holderDid the DID of the receiving party
+   * @param privateKey a private key (format unspecified)
+   * @param keyId the id of the private key
+   * @param vc a hash map representing a VC
+   * @return a signed JWT
    */
   @SneakyThrows
   public SignedJWT create(
@@ -172,11 +177,11 @@ public SignedJWT create(
   /**
    * Create a signedJwt for ES256 JWT {@link SignedJWT} with a set of claims
    *
-   * @param privateKey
-   * @param claimsSet
-   * @param issuer
-   * @param keyId
-   * @return
+   * @param issuer the string representation of the 'iss' claim
+   * @param privateKey a private key (format unspecified)
+   * @param keyId the id of the private key
+   * @param claimsSet the JWT claims object
+   * @return a signed JWT
    */
   public SignedJWT createSignedES256Jwt(
       OctetKeyPair privateKey, JWTClaimsSet claimsSet, String issuer, String keyId) {

src/main/java/org/eclipse/tractusx/ssi/lib/jwt/SignedJwtValidator.java

@@ -32,6 +32,13 @@
 /** The type Signed jwt validator. */
 public class SignedJwtValidator {
 
+  /**
+   * Validate the JWT has not expired
+   *
+   * @param jwt a signed JWT object
+   * @throws JwtExpiredException is thrown if the expiredDate is in the past
+   * @throws SignatureParseException is thrown if the signature cannot be validated
+   */
   public void validateDate(SignedJWT jwt) throws JwtExpiredException, SignatureParseException {
     Date expiryDate;
     try {
@@ -45,8 +52,16 @@ public void validateDate(SignedJWT jwt) throws JwtExpiredException, SignaturePar
     }
   }
 
+  /**
+   * Validates the audience of the JWT
+   *
+   * @param jwt as signed JWT
+   * @param expectedAudience is the expected audience inside the 'aud' claim
+   * @throws JwtAudienceCheckException is thrown if the audiences don't match
+   * @throws SignatureParseException is thrown if the signature cannot be verified
+   */
   public void validateAudiences(SignedJWT jwt, String expectedAudience)
-      throws JwtAudienceCheckException, SignatureParseException, JwtAudienceCheckException {
+      throws SignatureParseException, JwtAudienceCheckException {
     List<String> audiences;
     try {
       audiences = jwt.getJWTClaimsSet().getAudience();

src/main/java/org/eclipse/tractusx/ssi/lib/model/base/Base58Bitcoin.java

@@ -77,8 +77,10 @@ public static Base58Bitcoin create(String encoded) {
     return new Base58Bitcoin(decoded, encoded);
   }
 
+  /** decoded: the base58 bitcoin decoded payload */
   @JsonIgnore byte @NonNull [] decoded;
 
+  /** encoded: the base58 bitcoin encoded payload */
   @NonNull String encoded;
 
   @Override

src/main/java/org/eclipse/tractusx/ssi/lib/model/did/Service.java

@@ -28,6 +28,7 @@
 import lombok.ToString;
 import org.eclipse.tractusx.ssi.lib.serialization.SerializeUtil;
 
+/** A 'service' representation for a DID document */
 @ToString
 public class Service extends HashMap<String, Object> {
   /** The constant ID. */

src/main/java/org/eclipse/tractusx/ssi/lib/model/did/ServiceBuilder.java

@@ -25,6 +25,7 @@
 import java.util.Map;
 import lombok.ToString;
 
+/** The DID service builder */
 @ToString
 public class ServiceBuilder {
   private URI id;

src/main/java/org/eclipse/tractusx/ssi/lib/proof/ISigner.java

@@ -34,8 +34,9 @@ public interface ISigner {
    * @param hashedLinkedData the hashed linked data
    * @param privateKey the private key
    * @return the byte [ ]
-   * @throws SsiException the ssi exception
    * @throws InvalidPrivateKeyFormatException the invalide private key format
+   * @throws SignatureGenerateFailedException is thrown if the signature cannot be generatedction
+   *     Maven.ExecuteGoal
    */
   public byte[] sign(HashedLinkedData hashedLinkedData, IPrivateKey privateKey)
       throws InvalidPrivateKeyFormatException, SignatureGenerateFailedException;

src/main/java/org/eclipse/tractusx/ssi/lib/proof/LinkedDataProofGenerator.java

@@ -82,8 +82,9 @@ public static LinkedDataProofGenerator newInstance(SignatureType type)
    * @param verificationMethodId the verification method id
    * @param privateKey the private key
    * @return the proof
-   * @throws SsiException the ssi exception
-   * @throws InvalidPrivateKeyFormatException the invalide private key format
+   * @throws InvalidPrivateKeyFormatException is thrown if the private key is in an unknown format
+   * @throws SignatureGenerateFailedException is thrown if the signature cannot be created
+   * @throws TransformJsonLdException is thrown if the json-ld cannot be canonicalized
    */
   public Proof createProof(Verifiable verifiable, URI verificationMethodId, IPrivateKey privateKey)
       throws InvalidPrivateKeyFormatException, SignatureGenerateFailedException,

src/main/java/org/eclipse/tractusx/ssi/lib/proof/LinkedDataProofValidation.java

@@ -81,15 +81,16 @@ public static LinkedDataProofValidation newInstance(DidResolver didResolver) {
    * depending on Verification Method to resolve the DID Document and fetching the required Public
    * Key
    *
-   * @throws UnsupportedSignatureTypeException
-   * @throws DidDocumentResolverNotRegisteredException
-   * @throws NoVerificationKeyFoundException
-   * @throws SignatureVerificationFailedException
-   * @throws InvalidPublicKeyFormatException
-   * @throws DidParseException
-   * @throws SignatureParseException
-   * @throws TransformJsonLdException
-   * @throws InvalidJsonLdException
+   * @param verifiable is an object adhering to the 'Verifiable' contract (usually a VC or VP)
+   * @return a boolean indicating if the object is valid
+   * @throws UnsupportedSignatureTypeException is thrown when the signature algorithm is unknown
+   * @throws SignatureParseException is thrown if the signature cannot be parsed
+   * @throws DidParseException is thrown if the DID cannot be parsed
+   * @throws InvalidPublicKeyFormatException is thrown if the public key is in an unknown format
+   * @throws SignatureVerificationFailedException is thrown if the signature cannot be verified
+   * @throws NoVerificationKeyFoundException is thrown if the required public verification key
+   *     cannot be found
+   * @throws TransformJsonLdException if the json-ld cannot be canonicalized
    */
   public boolean verify(Verifiable verifiable)
       throws UnsupportedSignatureTypeException, SignatureParseException, DidParseException,

src/main/java/org/eclipse/tractusx/ssi/lib/proof/transform/LinkedDataTransformer.java

@@ -41,6 +41,13 @@
 /** The type Linked data transformer. */
 public class LinkedDataTransformer {
 
+  /**
+   * Canonicalize an object adhering to the 'Verifiable' contract.
+   *
+   * @param document is a VC or a VP (or any 'Verifiable' object)
+   * @return The canonical representation of the linked data (canonical json-ld representation)
+   * @throws TransformJsonLdException is thrown if the data cannot be canonicalized
+   */
   public TransformedLinkedData transform(Verifiable document) throws TransformJsonLdException {
 
     // We need Deep Clone to keep the original

src/main/java/org/eclipse/tractusx/ssi/lib/proof/types/jws/JWSProofVerifier.java

@@ -135,6 +135,17 @@ private OctetKeyPair discoverOctectKey(JWSSignature2020 signature)
     return new OctetKeyPair.Builder(Curve.Ed25519, x).build();
   }
 
+  /**
+   * Verify JWS of a JWT
+   *
+   * @param hashedLinkedData a json-ld as a hash map
+   * @param signature the byte representation of the signature
+   * @param publicKey the public key to use for the verification
+   * @return a boolean indicating if the signature is valid
+   * @throws SignatureParseException is thrown if the signature cannot be parsed
+   * @throws SignatureVerificationFailedException is thrown if the signature is invalid
+   * @throws InvalidPublicKeyFormatException is thrown if the public key is in an unsupported format
+   */
   public boolean verify(HashedLinkedData hashedLinkedData, byte[] signature, IPublicKey publicKey)
       throws SignatureParseException, SignatureVerificationFailedException,
           InvalidPublicKeyFormatException {