Add missing javadoc

sop-java/src/main/java/sop/operation/Dearmor.java

@@ -18,6 +18,9 @@ public interface Dearmor {
      *
      * @param data armored OpenPGP data
      * @return input stream of unarmored data
+     *
+     * @throws sop.exception.SOPGPException.BadData in case of non-OpenPGP data
+     * @throws IOException in case of an IO error
      */
     Ready data(InputStream data) throws SOPGPException.BadData, IOException;
 
@@ -26,6 +29,9 @@ public interface Dearmor {
      *
      * @param data armored OpenPGP data
      * @return input stream of unarmored data
+     *
+     * @throws sop.exception.SOPGPException.BadData in case of non-OpenPGP data
+     * @throws IOException in case of an IO error
      */
     default Ready data(byte[] data) throws SOPGPException.BadData, IOException {
         return data(new ByteArrayInputStream(data));

sop-java/src/main/java/sop/operation/Decrypt.java

@@ -21,6 +21,8 @@ public interface Decrypt {
      *
      * @param timestamp timestamp
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.UnsupportedOption if this option is not supported
      */
     Decrypt verifyNotBefore(Date timestamp)
             throws SOPGPException.UnsupportedOption;
@@ -30,6 +32,8 @@ public interface Decrypt {
      *
      * @param timestamp timestamp
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.UnsupportedOption if this option is not supported
      */
     Decrypt verifyNotAfter(Date timestamp)
             throws SOPGPException.UnsupportedOption;
@@ -39,6 +43,9 @@ public interface Decrypt {
      *
      * @param cert input stream containing the cert(s)
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.BadData if the {@link InputStream} doesn't provide an OpenPGP certificate
+     * @throws IOException in case of an IO error
      */
     Decrypt verifyWithCert(InputStream cert)
             throws SOPGPException.BadData,
@@ -49,6 +56,9 @@ public interface Decrypt {
      *
      * @param cert byte array containing the cert(s)
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.BadData if the byte array doesn't contain an OpenPGP certificate
+     * @throws IOException in case of an IO error
      */
     default Decrypt verifyWithCert(byte[] cert)
             throws SOPGPException.BadData, IOException {
@@ -60,6 +70,8 @@ public interface Decrypt {
      *
      * @param sessionKey session key
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.UnsupportedOption if this option is not supported
      */
     Decrypt withSessionKey(SessionKey sessionKey)
             throws SOPGPException.UnsupportedOption;
@@ -69,6 +81,9 @@ public interface Decrypt {
      *
      * @param password password
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.PasswordNotHumanReadable if the password is not human-readable
+     * @throws sop.exception.SOPGPException.UnsupportedOption if this option is not supported
      */
     Decrypt withPassword(String password)
             throws SOPGPException.PasswordNotHumanReadable,
@@ -79,6 +94,10 @@ public interface Decrypt {
      *
      * @param key input stream containing the key(s)
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.KeyIsProtected if the key is password protected
+     * @throws sop.exception.SOPGPException.BadData if the {@link InputStream} does not provide an OpenPGP key
+     * @throws sop.exception.SOPGPException.UnsupportedAsymmetricAlgo if the key uses an unsupported asymmetric algorithm
      */
     Decrypt withKey(InputStream key)
             throws SOPGPException.KeyIsProtected,
@@ -90,6 +109,10 @@ public interface Decrypt {
      *
      * @param key byte array containing the key(s)
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.KeyIsProtected if the key is password protected
+     * @throws sop.exception.SOPGPException.BadData if the byte array does not contain an OpenPGP key
+     * @throws sop.exception.SOPGPException.UnsupportedAsymmetricAlgo if the key uses an unsupported asymmetric algorithm
      */
     default Decrypt withKey(byte[] key)
             throws SOPGPException.KeyIsProtected,
@@ -102,6 +125,10 @@ public interface Decrypt {
      * Decrypts the given ciphertext, returning verification results and plaintext.
      * @param ciphertext ciphertext
      * @return ready with result
+     *
+     * @throws sop.exception.SOPGPException.BadData if the {@link InputStream} does not provide an OpenPGP message
+     * @throws sop.exception.SOPGPException.MissingArg in case of missing decryption method (password or key required)
+     * @throws sop.exception.SOPGPException.CannotDecrypt in case decryption fails for some reason
      */
     ReadyWithResult<DecryptionResult> ciphertext(InputStream ciphertext)
             throws SOPGPException.BadData, SOPGPException.MissingArg, SOPGPException.CannotDecrypt;
@@ -110,6 +137,10 @@ public interface Decrypt {
      * Decrypts the given ciphertext, returning verification results and plaintext.
      * @param ciphertext ciphertext
      * @return ready with result
+     *
+     * @throws sop.exception.SOPGPException.BadData if the byte array does not contain an encrypted OpenPGP message
+     * @throws sop.exception.SOPGPException.MissingArg in case of missing decryption method (password or key required)
+     * @throws sop.exception.SOPGPException.CannotDecrypt in case decryption fails for some reason
      */
     default ReadyWithResult<DecryptionResult> ciphertext(byte[] ciphertext)
         throws SOPGPException.BadData, SOPGPException.MissingArg, SOPGPException.CannotDecrypt {

sop-java/src/main/java/sop/operation/Encrypt.java

@@ -26,6 +26,8 @@ public interface Encrypt {
      *
      * @param mode mode
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.UnsupportedOption if this option is not supported
      */
     Encrypt mode(EncryptAs mode)
             throws SOPGPException.UnsupportedOption;
@@ -35,6 +37,11 @@ public interface Encrypt {
      *
      * @param key input stream containing the encoded signer key
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.KeyIsProtected if the key is password protected
+     * @throws sop.exception.SOPGPException.KeyCannotSign if the key is not capable of signing
+     * @throws sop.exception.SOPGPException.UnsupportedAsymmetricAlgo if the key uses an unsupported asymmetric algorithm
+     * @throws sop.exception.SOPGPException.BadData if the {@link InputStream} does not contain an OpenPGP key
      */
     Encrypt signWith(InputStream key)
             throws SOPGPException.KeyIsProtected,
@@ -47,6 +54,11 @@ public interface Encrypt {
      *
      * @param key byte array containing the encoded signer key
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.KeyIsProtected if the key is password protected
+     * @throws sop.exception.SOPGPException.KeyCannotSign if the key is not capable of signing
+     * @throws sop.exception.SOPGPException.UnsupportedAsymmetricAlgo if the key uses an unsupported asymmetric algorithm
+     * @throws sop.exception.SOPGPException.BadData if the byte array does not contain an OpenPGP key
      */
     default Encrypt signWith(byte[] key)
             throws SOPGPException.KeyIsProtected,
@@ -61,6 +73,9 @@ public interface Encrypt {
      *
      * @param password password
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.PasswordNotHumanReadable if the password is not human-readable
+     * @throws sop.exception.SOPGPException.UnsupportedOption if this option is not supported
      */
     Encrypt withPassword(String password)
             throws SOPGPException.PasswordNotHumanReadable,
@@ -71,6 +86,10 @@ public interface Encrypt {
      *
      * @param cert input stream containing the encoded cert.
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.CertCannotEncrypt if the certificate is not encryption capable
+     * @throws sop.exception.SOPGPException.UnsupportedAsymmetricAlgo if the certificate uses an unsupported asymmetric algorithm
+     * @throws sop.exception.SOPGPException.BadData if the {@link InputStream} does not contain an OpenPGP certificate
      */
     Encrypt withCert(InputStream cert)
             throws SOPGPException.CertCannotEncrypt,
@@ -82,6 +101,10 @@ public interface Encrypt {
      *
      * @param cert byte array containing the encoded cert.
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.CertCannotEncrypt if the certificate is not encryption capable
+     * @throws sop.exception.SOPGPException.UnsupportedAsymmetricAlgo if the certificate uses an unsupported asymmetric algorithm
+     * @throws sop.exception.SOPGPException.BadData if the byte array does not contain an OpenPGP certificate
      */
     default Encrypt withCert(byte[] cert)
             throws SOPGPException.CertCannotEncrypt,
@@ -94,6 +117,8 @@ public interface Encrypt {
      * Encrypt the given data yielding the ciphertext.
      * @param plaintext plaintext
      * @return input stream containing the ciphertext
+     *
+     * @throws IOException in case of an IO error
      */
     Ready plaintext(InputStream plaintext)
         throws IOException;
@@ -102,6 +127,8 @@ public interface Encrypt {
      * Encrypt the given data yielding the ciphertext.
      * @param plaintext plaintext
      * @return input stream containing the ciphertext
+     *
+     * @throws IOException in case of an IO error
      */
     default Ready plaintext(byte[] plaintext) throws IOException {
         return plaintext(new ByteArrayInputStream(plaintext));

sop-java/src/main/java/sop/operation/ExtractCert.java

@@ -25,6 +25,9 @@ public interface ExtractCert {
      *
      * @param keyInputStream input stream containing the encoding of one or more OpenPGP keys
      * @return result containing the encoding of the keys certs
+     *
+     * @throws IOException in case of an IO error
+     * @throws sop.exception.SOPGPException.BadData if the {@link InputStream} does not contain an OpenPGP key
      */
     Ready key(InputStream keyInputStream) throws IOException, SOPGPException.BadData;
 
@@ -33,6 +36,9 @@ public interface ExtractCert {
      *
      * @param key byte array containing the encoding of one or more OpenPGP key
      * @return result containing the encoding of the keys certs
+     *
+     * @throws IOException in case of an IO error
+     * @throws sop.exception.SOPGPException.BadData if the byte array does not contain an OpenPGP key
      */
     default Ready key(byte[] key) throws IOException, SOPGPException.BadData {
         return key(new ByteArrayInputStream(key));

sop-java/src/main/java/sop/operation/GenerateKey.java

@@ -31,6 +31,10 @@ public interface GenerateKey {
      * Generate the OpenPGP key and return it encoded as an {@link InputStream}.
      *
      * @return key
+     *
+     * @throws sop.exception.SOPGPException.MissingArg if no user-id was provided
+     * @throws sop.exception.SOPGPException.UnsupportedAsymmetricAlgo if the generated key uses an unsupported asymmetric algorithm
+     * @throws IOException in case of an IO error
      */
     Ready generate() throws SOPGPException.MissingArg, SOPGPException.UnsupportedAsymmetricAlgo, IOException;
 }

sop-java/src/main/java/sop/operation/Sign.java

@@ -28,6 +28,8 @@ public interface Sign {
      *
      * @param mode signature mode
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.UnsupportedOption if this option is not supported
      */
     Sign mode(SignAs mode) throws SOPGPException.UnsupportedOption;
 
@@ -36,6 +38,10 @@ public interface Sign {
      *
      * @param key input stream containing encoded keys
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.KeyIsProtected if the key is password protected
+     * @throws sop.exception.SOPGPException.BadData if the {@link InputStream} does not contain an OpenPGP key
+     * @throws IOException in case of an IO error
      */
     Sign key(InputStream key) throws SOPGPException.KeyIsProtected, SOPGPException.BadData, IOException;
 
@@ -44,6 +50,10 @@ public interface Sign {
      *
      * @param key byte array containing encoded keys
      * @return builder instance
+     *
+     * @throws sop.exception.SOPGPException.KeyIsProtected if the key is password protected
+     * @throws sop.exception.SOPGPException.BadData if the byte array does not contain an OpenPGP key
+     * @throws IOException in case of an IO error
      */
     default Sign key(byte[] key) throws SOPGPException.KeyIsProtected, SOPGPException.BadData, IOException {
         return key(new ByteArrayInputStream(key));
@@ -54,6 +64,9 @@ public interface Sign {
      *
      * @param data input stream containing data
      * @return ready
+     *
+     * @throws IOException in case of an IO error
+     * @throws sop.exception.SOPGPException.ExpectedText if text data was expected, but binary data was encountered
      */
     ReadyWithResult<SigningResult> data(InputStream data) throws IOException, SOPGPException.ExpectedText;
 
@@ -62,6 +75,9 @@ public interface Sign {
      *
      * @param data byte array containing data
      * @return ready
+     *
+     * @throws IOException in case of an IO error
+     * @throws sop.exception.SOPGPException.ExpectedText if text data was expected, but binary data was encountered
      */
     default ReadyWithResult<SigningResult> data(byte[] data) throws IOException, SOPGPException.ExpectedText {
         return data(new ByteArrayInputStream(data));

sop-java/src/main/java/sop/util/UTF8Util.java

@@ -24,8 +24,9 @@ public class UTF8Util {
      * Detect non-valid UTF8 data.
      *
      * @see <a href="https://stackoverflow.com/a/1471193">ante on StackOverflow</a>
-     * @param data
+     * @param data utf-8 encoded bytes
-     * @return
+     *
+     * @return decoded string
      */
     public static String decodeUTF8(byte[] data) {
         ByteBuffer byteBuffer = ByteBuffer.wrap(data);