Add missing javadoc

vks-java/src/main/java/pgp/vks/client/RequestVerify.java

@@ -9,20 +9,54 @@ import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Request email verification for email addresses of user-ids on a certificate.
+ */
 public interface RequestVerify {
 
+    /**
+     * Request email verification for the given email address.
+     *
+     * @param emailAddress email address
+     * @return builder
+     */
     default ForEmailAddresses forEmailAddress(String emailAddress) {
         return forEmailAddresses(emailAddress);
     }
 
+    /**
+     * Request email verification for one or more email addresses.
+     *
+     * @param emailAddresses email addresses
+     * @return builder
+     */
     ForEmailAddresses forEmailAddresses(String... emailAddresses);
 
     interface ForEmailAddresses {
 
+        /**
+         * Execute the verification request using the given <pre>token</pre>, retrieved earlier by uploading the
+         * certificate to the server.
+         *
+         * @param token access token to authorize the request
+         * @return servers successful response
+         *
+         * @throws IOException in case of an error
+         */
         default Response execute(String token) throws IOException {
             return execute(token, Arrays.asList("en_US", "en_GB"));
         }
 
+        /**
+         * Execute the verification request using the given <pre>token</pre>, retrieved earlier by uploading the
+         * certificate to the server.
+         *
+         * @param token access token to authorize the request
+         * @param locale list of preferred locales for the verification emails
+         * @return servers successful response
+         *
+         * @throws IOException in case of an error
+         */
         Response execute(String token, List<String> locale) throws IOException;
 
     }
@@ -41,14 +75,29 @@ public interface RequestVerify {
             this.token = token;
         }
 
+        /**
+         * Return the uppercase OpenPGP fingerprint of the certificate.
+         *
+         * @return fingerprint
+         */
         public String getKeyFingerprint() {
             return keyFingerprint;
         }
 
+        /**
+         * Return a map of {@link Status States} of email addresses of user-ids on the certificate after requesting
+         * verification.
+         * @return status map
+         */
         public Map<String, Status> getStatus() {
             return status;
         }
 
+        /**
+         * Return an access token to be used to make further requests to the API.
+         *
+         * @return token
+         */
         public String getToken() {
             return token;
         }

vks-java/src/main/java/pgp/vks/client/Status.java

@@ -4,6 +4,9 @@
 
 package pgp.vks.client;
 
+/**
+ * Enum representing different states an email address of a user-id on a certificate can be in.
+ */
 public enum Status {
 
     /**

vks-java/src/main/java/pgp/vks/client/VKSImpl.java

@@ -27,6 +27,11 @@ public class VKSImpl implements VKS {
         this.api = new URLMapper(vksService);
     }
 
+    /**
+     * Return a {@link VKSImpl} instance targeting the <pre>https://keys.openpgp.org</pre> VKS.
+     *
+     * @return VKS instance
+     */
     @SneakyThrows
     public static VKS keysDotOpenPgpDotOrg() {
         return new VKSImpl("https://keys.openpgp.org");

vks-java/src/main/java/pgp/vks/client/exception/CertCannotBePublishedException.java

@@ -6,6 +6,9 @@ package pgp.vks.client.exception;
 
 import java.net.ConnectException;
 
+/**
+ * Exception gets thrown when a public key certificate cannot be published for some reason.
+ */
 public class CertCannotBePublishedException extends ConnectException {
 
     public CertCannotBePublishedException(String errorMessage) {

vks-java/src/main/java/pgp/vks/client/exception/CertNotFoundException.java

@@ -6,12 +6,11 @@ package pgp.vks.client.exception;
 
 import java.net.ConnectException;
 
+/**
+ * Exception gets thrown when the queried OpenPGP certificate cannot be found on the server.
+ */
 public class CertNotFoundException extends ConnectException {
 
-    public CertNotFoundException() {
-        super();
-    }
-
     public CertNotFoundException(String message) {
         super(message);
     }

vks-java/src/main/java/pgp/vks/client/exception/UnsupportedApiException.java

@@ -4,6 +4,10 @@
 
 package pgp.vks.client.exception;
 
+/**
+ * Exception gets thrown when an unsupported API {@link pgp.vks.client.VKS.Version} is used.
+ * E.g. user wants to use some command using v2 API, but implementation only supports v1.
+ */
 public class UnsupportedApiException extends RuntimeException {
 
     public UnsupportedApiException(String message) {

vks-java/src/main/java/pgp/vks/client/v1/dto/ErrorResponseDto.java

@@ -6,6 +6,11 @@ package pgp.vks.client.v1.dto;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 
+/**
+ * Error response that gets returned by the server if a POST request fails.
+ *
+ * @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
+ */
 public class ErrorResponseDto {
 
     private final String error;
@@ -14,6 +19,11 @@ public class ErrorResponseDto {
         this.error = error;
     }
 
+    /**
+     * Return the error message.
+     *
+     * @return error message
+     */
     @JsonProperty("error")
     public String getError() {
         return error;

vks-java/src/main/java/pgp/vks/client/v1/dto/UploadRequestDto.java

@@ -14,6 +14,11 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.nio.charset.Charset;
 
+/**
+ * Request for uploading a certificate to the VKS.
+ *
+ * @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
+ */
 public class UploadRequestDto {
 
     private static final byte[] ARMOR_HEADER = "-----BEGIN PGP PUBLIC KEY BLOCK-----".getBytes(Charset.forName("UTF8"));
@@ -24,6 +29,15 @@ public class UploadRequestDto {
         this.keytext = keytext;
     }
 
+    /**
+     * Create an {@link UploadRequestDto} from an ASCII armored or binary OpenPGP certificate which is read from the
+     * given <pre>certInStream</pre>.
+     *
+     * @param certInStream {@link InputStream} containing the ASCII armored or binary OpenPGP certificate
+     * @return request DTO
+     *
+     * @throws IOException in case of an IO error
+     */
     public static UploadRequestDto fromInputStream(InputStream certInStream) throws IOException {
         ByteArrayOutputStream certBuf = new ByteArrayOutputStream();
         Streams.pipeAll(certInStream, certBuf);
@@ -31,11 +45,26 @@ public class UploadRequestDto {
         return fromBytes(certBuf.toByteArray());
     }
 
+    /**
+     * Create an {@link UploadRequestDto} from an ASCII armored or binary OpenPGP certificate which is read from the
+     * given <pre>keytext</pre> byte array.
+     *
+     * @param keytext byte array containing the ASCII armored or binary OpenPGP certificate
+     * @return request DTO
+     */
     public static UploadRequestDto fromBytes(byte[] keytext) {
         String armoredOrBase64 = new String(base64IfNecessary(keytext));
         return new UploadRequestDto(armoredOrBase64);
     }
 
+    /**
+     * Prepare a serialized OpenPGP certificate for upload.
+     * If the given <pre>certBytes</pre> contain an ASCII armored OpenPGP certificate, do nothing.
+     * Otherwise, consider the bytes to be the binary representation of an OpenPGP certificate and wrap it in Base64 encoding.
+     *
+     * @param certBytes certificate bytes
+     * @return Unmodified ASCII armored, or base64 encoded binary OpenPGP certificate
+     */
     private static byte[] base64IfNecessary(byte[] certBytes) {
         if (!Arrays.areEqual(certBytes, 0, ARMOR_HEADER.length, ARMOR_HEADER, 0, ARMOR_HEADER.length)) {
             certBytes = Base64.encode(certBytes);

vks-java/src/main/java/pgp/vks/client/v1/dto/UploadResponseDto.java

@@ -11,6 +11,11 @@ import pgp.vks.client.Upload;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * The VKS servers response to a successful upload.
+ *
+ * @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
+ */
 public class UploadResponseDto {
 
     private final String key_fpr;
@@ -25,21 +30,41 @@ public class UploadResponseDto {
         this.token = token;
     }
 
+    /**
+     * Uppercase fingerprint of the uploaded OpenPGP certificate.
+     *
+     * @return fingerprint
+     */
     @JsonProperty("key_fpr")
     public String getKeyFingerprint() {
         return key_fpr;
     }
 
+    /**
+     * Access token which can be used for a limited time to request verification emails for user-ids on the certificate.
+     *
+     * @return access token
+     */
     @JsonProperty("token")
     public String getToken() {
         return token;
     }
 
+    /**
+     * Map of {@link Status States} of email addresses of user-ids on the certificate.
+     *
+     * @return email status map
+     */
     @JsonProperty("status")
     public Map<String, Status> getStatus() {
         return new HashMap<>(status);
     }
 
+    /**
+     * Convert the DTO into an entity.
+     *
+     * @return entity
+     */
     public Upload.Response toEntity() {
         return new Upload.Response(getKeyFingerprint(), getStatus(), getToken());
     }

vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationRequestDto.java

@@ -8,6 +8,11 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 
 import java.util.List;
 
+/**
+ * Request for email verification of one or more unpublished/pending user-ids.
+ *
+ * @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
+ */
 public class VerificationRequestDto {
 
     private final String token;
@@ -22,16 +27,31 @@ public class VerificationRequestDto {
         this.locale = locale;
     }
 
+    /**
+     * Return the token which was previously required by uploading a certificate using an {@link UploadRequestDto}.
+     *
+     * @return access token used to authenticate the request
+     */
     @JsonProperty("token")
     public String getToken() {
         return token;
     }
 
+    /**
+     * {@link List} of email addresses for which to request email verification.
+     *
+     * @return email addresses
+     */
     @JsonProperty("addresses")
     public List<String> getAddresses() {
         return addresses;
     }
 
+    /**
+     * {@link List} of preferred locales for the verification mails.
+     *
+     * @return locale list
+     */
     @JsonProperty("locale")
     public List<String> getLocale() {
         return locale;

vks-java/src/main/java/pgp/vks/client/v1/dto/VerificationResponseDto.java

@@ -10,6 +10,11 @@ import pgp.vks.client.Status;
 
 import java.util.Map;
 
+/**
+ * VKS servers response to a successful verification request.
+ *
+ * @see <a href="https://keys.openpgp.org/about/api">VKS API Documentation</a>
+ */
 public class VerificationResponseDto {
 
     private final String key_fpr;
@@ -24,21 +29,41 @@ public class VerificationResponseDto {
         this.token = token;
     }
 
+    /**
+     * Uppercase OpenPGP fingerprint of the certificate.
+     *
+     * @return fingerprint
+     */
     @JsonProperty("key_fpr")
     public String getKeyFingerprint() {
         return key_fpr;
     }
 
+    /**
+     * Access token which can be used to authenticate further verification requests.
+     *
+     * @return token
+     */
     @JsonProperty("token")
     public String getToken() {
         return token;
     }
 
+    /**
+     * Map of {@link Status States} of email addresses of user-ids on the certificate.
+     *
+     * @return email address status map
+     */
     @JsonProperty("status")
     public Map<String, Status> getStatus() {
         return status;
     }
 
+    /**
+     * Convert this DTO to an entity.
+     *
+     * @return entity
+     */
     public RequestVerify.Response toEntity() {
         return new RequestVerify.Response(getKeyFingerprint(), getStatus(), getToken());
     }