Fix javadoc warnings

pgpainless-core/src/main/java/org/pgpainless/PGPainless.java

@@ -71,6 +71,8 @@ public final class PGPainless {
      *
      * @param key key or certificate
      * @return ascii armored string
+     *
+     * @throws IOException in case of an error in the {@link org.bouncycastle.bcpg.ArmoredOutputStream}
      */
     public static String asciiArmor(@Nonnull PGPKeyRing key) throws IOException {
         if (key instanceof PGPSecretKeyRing) {

pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MessageInspector.java

@@ -75,6 +75,9 @@ public final class MessageInspector {
      *
      * @param message OpenPGP message
      * @return encryption info
+     *
+     * @throws PGPException in case the message is broken
+     * @throws IOException in case of an IO error
      */
     public static EncryptionInfo determineEncryptionInfoForMessage(String message) throws PGPException, IOException {
         @SuppressWarnings("CharsetObjectCanBeUsed")
@@ -88,6 +91,9 @@ public final class MessageInspector {
      *
      * @param dataIn openpgp message
      * @return encryption information
+     *
+     * @throws IOException in case of an IO error
+     * @throws PGPException if the message is broken
      */
     public static EncryptionInfo determineEncryptionInfoForMessage(InputStream dataIn) throws IOException, PGPException {
         InputStream decoded = ArmorUtils.getDecoderStream(dataIn);

pgpainless-core/src/main/java/org/pgpainless/decryption_verification/cleartext_signatures/ClearsignedMessageUtil.java

@@ -35,7 +35,9 @@ public final class ClearsignedMessageUtil {
      * @param clearsignedInputStream input stream containing a clearsigned message
      * @param messageOutputStream output stream to which the dearmored message shall be written
      * @return signatures
+     *
      * @throws IOException if the message is not clearsigned or some other IO error happens
+     * @throws WrongConsumingMethodException in case the armored message is not cleartext signed
      */
     public static PGPSignatureList detachSignaturesFromInbandClearsignedMessage(InputStream clearsignedInputStream,
                                                                                 OutputStream messageOutputStream)

pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionBuilderInterface.java

@@ -27,7 +27,10 @@ public interface EncryptionBuilderInterface {
          * Create an {@link EncryptionStream} with the given options (recipients, signers, algorithms...).
          *
          * @param options options
-         * @return encryption strea
+         * @return encryption stream
+         *
+         * @throws PGPException if something goes wrong during encryption stream preparation
+         * @throws IOException if something goes wrong during encryption stream preparation (writing headers)
          */
         EncryptionStream withOptions(ProducerOptions options) throws PGPException, IOException;
 

pgpainless-core/src/main/java/org/pgpainless/encryption_signing/EncryptionOptions.java

@@ -282,6 +282,7 @@ public class EncryptionOptions {
      * If the algorithm is not overridden, a suitable algorithm will be negotiated.
      *
      * @param encryptionAlgorithm encryption algorithm override
+     * @return this
      */
     public EncryptionOptions overrideEncryptionAlgorithm(SymmetricKeyAlgorithm encryptionAlgorithm) {
         if (encryptionAlgorithm == SymmetricKeyAlgorithm.NULL) {

pgpainless-core/src/main/java/org/pgpainless/encryption_signing/SigningOptions.java

@@ -58,6 +58,7 @@ public final class SigningOptions {
          * The resulting signature will be written into the message itself, together with a one-pass-signature packet.
          *
          * @param signatureGenerator signature generator
+         * @param hashAlgorithm hash algorithm used to generate the signature
          * @return inline signing method
          */
         public static SigningMethod inlineSignature(PGPSignatureGenerator signatureGenerator, HashAlgorithm hashAlgorithm) {
@@ -70,6 +71,7 @@ public final class SigningOptions {
          * to the signed message.
          *
          * @param signatureGenerator signature generator
+         * @param hashAlgorithm hash algorithm used to generate the signature
          * @return detached signing method
          */
         public static SigningMethod detachedSignature(PGPSignatureGenerator signatureGenerator, HashAlgorithm hashAlgorithm) {

pgpainless-core/src/main/java/org/pgpainless/key/generation/KeyRingTemplates.java

@@ -33,6 +33,10 @@ public final class KeyRingTemplates {
      * @param length length in bits.
      *
      * @return {@link PGPSecretKeyRing} containing the KeyPair.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull UserId userId, @Nonnull RsaLength length)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException {
@@ -47,6 +51,10 @@ public final class KeyRingTemplates {
      * @param length length in bits.
      *
      * @return {@link PGPSecretKeyRing} containing the KeyPair.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull String userId, @Nonnull RsaLength length)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException {
@@ -62,6 +70,10 @@ public final class KeyRingTemplates {
      * @param password Password of the key. Can be null for unencrypted keys.
      *
      * @return {@link PGPSecretKeyRing} containing the KeyPair.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull UserId userId, @Nonnull RsaLength length, String password)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException {
@@ -77,6 +89,10 @@ public final class KeyRingTemplates {
      * @param password Password of the key. Can be null for unencrypted keys.
      *
      * @return {@link PGPSecretKeyRing} containing the KeyPair.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleRsaKeyRing(@Nonnull String userId, @Nonnull RsaLength length, String password)
             throws PGPException, NoSuchAlgorithmException, InvalidAlgorithmParameterException {
@@ -98,6 +114,10 @@ public final class KeyRingTemplates {
      * @param userId user-id
      *
      * @return {@link PGPSecretKeyRing} containing the key pairs.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleEcKeyRing(@Nonnull UserId userId)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException {
@@ -112,6 +132,10 @@ public final class KeyRingTemplates {
      * @param userId user-id
      *
      * @return {@link PGPSecretKeyRing} containing the key pairs.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleEcKeyRing(@Nonnull String userId)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException {
@@ -127,6 +151,10 @@ public final class KeyRingTemplates {
      * @param password Password of the private key. Can be null for an unencrypted key.
      *
      * @return {@link PGPSecretKeyRing} containing the key pairs.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleEcKeyRing(@Nonnull UserId userId, String password)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException {
@@ -142,6 +170,10 @@ public final class KeyRingTemplates {
      * @param password Password of the private key. Can be null for an unencrypted key.
      *
      * @return {@link PGPSecretKeyRing} containing the key pairs.
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing simpleEcKeyRing(@Nonnull String userId, String password)
             throws PGPException, NoSuchAlgorithmException, InvalidAlgorithmParameterException {
@@ -163,6 +195,10 @@ public final class KeyRingTemplates {
      * @param userId primary user id
      * @param password passphrase or null if the key should be unprotected.
      * @return key ring
+     *
+     * @throws InvalidAlgorithmParameterException in case of invalid key generation parameters
+     * @throws NoSuchAlgorithmException in case of missing algorithm implementation in the crypto provider
+     * @throws PGPException in case of an OpenPGP related error
      */
     public PGPSecretKeyRing modernKeyRing(String userId, String password)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException, PGPException {

pgpainless-core/src/main/java/org/pgpainless/key/modification/secretkeyring/SecretKeyRingEditorInterface.java

@@ -34,6 +34,8 @@ public interface SecretKeyRingEditorInterface {
      * @param userId user-id
      * @param secretKeyRingProtector protector to unlock the secret key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a signature for the user-id
      */
     SecretKeyRingEditorInterface addUserId(
             @Nonnull CharSequence userId,
@@ -48,6 +50,8 @@ public interface SecretKeyRingEditorInterface {
      *                                   certification signature.
      * @param protector protector to unlock the primary secret key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a signature for the user-id
      */
     SecretKeyRingEditorInterface addUserId(
             @Nonnull CharSequence userId,
@@ -62,6 +66,8 @@ public interface SecretKeyRingEditorInterface {
      * @param userId user id
      * @param protector protector to unlock the secret key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a signature for the user-id
      */
     SecretKeyRingEditorInterface addPrimaryUserId(
             @Nonnull CharSequence userId,
@@ -76,6 +82,8 @@ public interface SecretKeyRingEditorInterface {
      * @param userIdSelector selector to select user-ids
      * @param protector protector to unlock the primary key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the user-id
      */
     SecretKeyRingEditorInterface removeUserId(SelectUserId userIdSelector,
                                               SecretKeyRingProtector protector)
@@ -89,6 +97,8 @@ public interface SecretKeyRingEditorInterface {
      * @param userId user-id to revoke
      * @param protector protector to unlock the primary key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the user-id
      */
     SecretKeyRingEditorInterface removeUserId(CharSequence userId,
                                               SecretKeyRingProtector protector)
@@ -102,6 +112,11 @@ public interface SecretKeyRingEditorInterface {
      * @param subKeyPassphrase passphrase to encrypt the sub key
      * @param secretKeyRingProtector protector to unlock the secret key of the key ring
      * @return the builder
+     *
+     * @throws InvalidAlgorithmParameterException in case the user wants to use invalid parameters for the key
+     * @throws NoSuchAlgorithmException in case of missing algorithm support in the crypto backend
+     * @throws PGPException in case we cannot generate a binding signature for the subkey
+     * @throws IOException in case of an IO error
      */
     SecretKeyRingEditorInterface addSubKey(
             @Nonnull KeySpec keySpec,
@@ -118,6 +133,11 @@ public interface SecretKeyRingEditorInterface {
      * @param subpacketsCallback callback to modify the subpackets of the subkey binding signature
      * @param secretKeyRingProtector protector to unlock the primary key
      * @return builder
+     *
+     * @throws InvalidAlgorithmParameterException in case the user wants to use invalid parameters for the key
+     * @throws NoSuchAlgorithmException in case of missing algorithm support in the crypto backend
+     * @throws PGPException in case we cannot generate a binding signature for the subkey
+     * @throws IOException in case of an IO error
      */
     SecretKeyRingEditorInterface addSubKey(
             @Nonnull KeySpec keySpec,
@@ -136,6 +156,10 @@ public interface SecretKeyRingEditorInterface {
      * @param keyFlag first key flag for the subkey
      * @param additionalKeyFlags optional additional key flags
      * @return builder
+     *
+     * @throws PGPException in case we cannot generate a binding signature for the subkey
+     * @throws IOException in case of an IO error
+     * @throws NoSuchAlgorithmException in case of missing algorithm support in the crypto backend
      */
     SecretKeyRingEditorInterface addSubKey(
             @Nonnull PGPKeyPair subkey,
@@ -152,6 +176,8 @@ public interface SecretKeyRingEditorInterface {
      *
      * @param secretKeyRingProtector protector of the primary key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature
      */
     default SecretKeyRingEditorInterface revoke(
             @Nonnull SecretKeyRingProtector secretKeyRingProtector)
@@ -166,6 +192,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector of the primary key
      * @param revocationAttributes reason for the revocation
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature
      */
     SecretKeyRingEditorInterface revoke(
             @Nonnull SecretKeyRingProtector secretKeyRingProtector,
@@ -180,6 +208,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary secret key
      * @param subpacketsCallback callback to modify the revocations subpackets
      * @return builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature
      */
     SecretKeyRingEditorInterface revoke(
             @Nonnull SecretKeyRingProtector secretKeyRingProtector,
@@ -198,6 +228,8 @@ public interface SecretKeyRingEditorInterface {
      * @param fingerprint fingerprint of the subkey to be revoked
      * @param secretKeyRingProtector protector to unlock the secret key ring
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the subkey
      */
     default SecretKeyRingEditorInterface revokeSubKey(
             @Nonnull OpenPgpFingerprint fingerprint,
@@ -215,6 +247,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary key
      * @param revocationAttributes reason for the revocation
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the subkey
      */
     default SecretKeyRingEditorInterface revokeSubKey(
             OpenPgpFingerprint fingerprint,
@@ -235,6 +269,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary key
      * @param revocationAttributes reason for the revocation
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the subkey
      */
     SecretKeyRingEditorInterface revokeSubKey(
             long subKeyId,
@@ -255,6 +291,8 @@ public interface SecretKeyRingEditorInterface {
      * @param subKeyId id of the subkey
      * @param secretKeyRingProtector protector to unlock the secret key ring
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the subkey
      */
     default SecretKeyRingEditorInterface revokeSubKey(
             long subKeyId,
@@ -279,6 +317,8 @@ public interface SecretKeyRingEditorInterface {
      * @param subpacketsCallback callback which can be used to modify the subpackets of the revocation
      *                           signature
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the subkey
      */
     SecretKeyRingEditorInterface revokeSubKey(
             long keyID,
@@ -296,6 +336,8 @@ public interface SecretKeyRingEditorInterface {
      * @param userId userId to revoke
      * @param secretKeyRingProtector protector to unlock the primary key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the user-id
      */
     default SecretKeyRingEditorInterface revokeUserId(
             @Nonnull CharSequence userId,
@@ -311,6 +353,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary key
      * @param revocationAttributes reason for the revocation
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the user-id
      */
     SecretKeyRingEditorInterface revokeUserId(
             @Nonnull CharSequence userId,
@@ -329,6 +373,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary secret key
      * @param subpacketCallback callback to modify the revocations subpackets
      * @return builder
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the user-id
      */
     SecretKeyRingEditorInterface revokeUserId(
             @Nonnull CharSequence userId,
@@ -348,7 +394,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary secret key
      * @param revocationAttributes revocation attributes
      * @return builder
-     * @throws PGPException if the revocation signatures cannot be generated
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the user-id
      */
     SecretKeyRingEditorInterface revokeUserIds(
             @Nonnull SelectUserId userIdSelector,
@@ -370,7 +417,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary secret key
      * @param subpacketsCallback callback to modify the revocations subpackets
      * @return builder
-     * @throws PGPException if the revocation signatures cannot be generated
+     *
+     * @throws PGPException in case we cannot generate a revocation signature for the user-id
      */
     SecretKeyRingEditorInterface revokeUserIds(
             @Nonnull SelectUserId userIdSelector,
@@ -385,6 +433,8 @@ public interface SecretKeyRingEditorInterface {
      * @param expiration new expiration date or null
      * @param secretKeyRingProtector to unlock the secret key
      * @return the builder
+     *
+     * @throws PGPException in case we cannot generate a new self-signature with the changed expiration date
      */
     SecretKeyRingEditorInterface setExpirationDate(
             @Nullable Date expiration,
@@ -397,6 +447,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary key.
      * @param revocationAttributes reason for the revocation
      * @return revocation certificate
+     *
+     * @throws PGPException in case we cannot generate a revocation certificate
      */
     PGPSignature createRevocationCertificate(
             @Nonnull SecretKeyRingProtector secretKeyRingProtector,
@@ -410,6 +462,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary key.
      * @param revocationAttributes reason for the revocation
      * @return revocation certificate
+     *
+     * @throws PGPException in case we cannot generate a revocation certificate
      */
     PGPSignature createRevocationCertificate(
             long subkeyId,
@@ -424,6 +478,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary key.
      * @param certificateSubpacketsCallback callback to modify the subpackets of the revocation certificate.
      * @return revocation certificate
+     *
+     * @throws PGPException in case we cannot generate a revocation certificate
      */
     PGPSignature createRevocationCertificate(
             long subkeyId,
@@ -438,6 +494,8 @@ public interface SecretKeyRingEditorInterface {
      * @param secretKeyRingProtector protector to unlock the primary key.
      * @param revocationAttributes reason for the revocation
      * @return revocation certificate
+     *
+     * @throws PGPException in case we cannot generate a revocation certificate
      */
     default PGPSignature createRevocationCertificate(
             OpenPgpFingerprint subkeyFingerprint,
@@ -521,6 +579,8 @@ public interface SecretKeyRingEditorInterface {
          *
          * @param passphrase passphrase
          * @return editor builder
+         *
+         * @throws PGPException in case the passphrase cannot be changed
          */
         SecretKeyRingEditorInterface toNewPassphrase(Passphrase passphrase)
                 throws PGPException;
@@ -529,6 +589,8 @@ public interface SecretKeyRingEditorInterface {
          * Leave the key unprotected.
          *
          * @return editor builder
+         *
+         * @throws PGPException in case the passphrase cannot be changed
          */
         SecretKeyRingEditorInterface toNoPassphrase() throws PGPException;
     }

pgpainless-core/src/main/java/org/pgpainless/key/parsing/KeyRingReader.java

@@ -107,6 +107,8 @@ public class KeyRingReader {
      * @param inputStream input stream
      * @param maxIterations max iterations before abort
      * @return public key ring
+     *
+     * @throws IOException in case of an IO error or exceeding of max iterations
      */
     public static PGPPublicKeyRing readPublicKeyRing(@Nonnull InputStream inputStream, int maxIterations) throws IOException {
         PGPObjectFactory objectFactory = ImplementationFactory.getInstance().getPGPObjectFactory(
@@ -142,6 +144,9 @@ public class KeyRingReader {
      * @param inputStream input stream
      * @param maxIterations max iterations before abort
      * @return public key ring collection
+     *
+     * @throws IOException in case of an IO error or exceeding of max iterations
+     * @throws PGPException in case of a broken key
      */
     public static PGPPublicKeyRingCollection readPublicKeyRingCollection(@Nonnull InputStream inputStream, int maxIterations)
             throws IOException, PGPException {
@@ -186,6 +191,8 @@ public class KeyRingReader {
      * @param inputStream input stream
      * @param maxIterations max iterations before abort
      * @return public key ring
+     *
+     * @throws IOException in case of an IO error or exceeding of max iterations
      */
     public static PGPSecretKeyRing readSecretKeyRing(@Nonnull InputStream inputStream, int maxIterations) throws IOException {
         InputStream decoderStream = ArmorUtils.getDecoderStream(inputStream);
@@ -222,6 +229,9 @@ public class KeyRingReader {
      * @param inputStream input stream
      * @param maxIterations max iterations before abort
      * @return secret key ring collection
+     *
+     * @throws IOException in case of an IO error or exceeding of max iterations
+     * @throws PGPException in case of a broken secret key
      */
     public static PGPSecretKeyRingCollection readSecretKeyRingCollection(@Nonnull InputStream inputStream,
                                                                          int maxIterations)

pgpainless-core/src/main/java/org/pgpainless/key/protection/SecretKeyRingProtector.java

@@ -37,6 +37,8 @@ public interface SecretKeyRingProtector {
      *
      * @param keyId id of the key
      * @return decryptor for the key
+     *
+     * @throws PGPException if the decryptor cannot be created for some reason
      */
     @Nullable PBESecretKeyDecryptor getDecryptor(Long keyId) throws PGPException;
 
@@ -46,6 +48,7 @@ public interface SecretKeyRingProtector {
      *
      * @param keyId id of the key
      * @return encryptor for the key
+     *
      * @throws PGPException if the encryptor cannot be created for some reason
      */
     @Nullable PBESecretKeyEncryptor getEncryptor(Long keyId) throws PGPException;

pgpainless-core/src/main/java/org/pgpainless/key/util/KeyRingUtils.java

@@ -429,8 +429,8 @@ public final class KeyRingUtils {
      * @param secretKeyId id of the secret key to remove
      * @return secret key ring with removed secret key
      *
-     * @throws IOException
+     * @throws IOException in case of an error during serialization / deserialization of the key
-     * @throws PGPException
+     * @throws PGPException in case of a broken key
      *
      * @deprecated use {@link #stripSecretKey(PGPSecretKeyRing, long)} instead.
      * TODO: Remove in 1.2.X
@@ -453,8 +453,8 @@ public final class KeyRingUtils {
      * @param secretKeyId id of the secret key to remove
      * @return secret key ring with removed secret key
      *
-     * @throws IOException
+     * @throws IOException in case of an error during serialization / deserialization of the key
-     * @throws PGPException
+     * @throws PGPException in case of a broken key
      */
     @Nonnull
     public static PGPSecretKeyRing stripSecretKey(@Nonnull PGPSecretKeyRing secretKeys,

pgpainless-core/src/main/java/org/pgpainless/signature/SignatureUtils.java

@@ -193,7 +193,9 @@ public final class SignatureUtils {
      *
      * @param encodedSignatures ASCII armored signature list
      * @return signature list
+     *
      * @throws IOException if the signatures cannot be read
+     * @throws PGPException in case of a broken signature
      */
     public static List<PGPSignature> readSignatures(String encodedSignatures) throws IOException, PGPException {
         @SuppressWarnings("CharsetObjectCanBeUsed")

pgpainless-core/src/main/java/org/pgpainless/signature/builder/AbstractSignatureBuilder.java

@@ -114,6 +114,8 @@ public abstract class AbstractSignatureBuilder<B extends AbstractSignatureBuilde
      * and with hashed and unhashed subpackets.
      *
      * @return pgp signature generator
+     *
+     * @throws PGPException if the signature generator cannot be initialized
      */
     protected PGPSignatureGenerator buildAndInitSignatureGenerator() throws PGPException {
         PGPSignatureGenerator generator = new PGPSignatureGenerator(

pgpainless-core/src/main/java/org/pgpainless/signature/builder/ThirdPartyCertificationSignatureBuilder.java

@@ -84,6 +84,8 @@ public class ThirdPartyCertificationSignatureBuilder extends AbstractSignatureBu
      * @param certifiedKey key ring
      * @param userId user-id to certify
      * @return signature
+     *
+     * @throws PGPException if the signature generator cannot be initialized
      */
     public PGPSignature build(PGPPublicKeyRing certifiedKey, String userId) throws PGPException {
         return buildAndInitSignatureGenerator().generateCertification(userId, certifiedKey.getPublicKey());
@@ -94,6 +96,8 @@ public class ThirdPartyCertificationSignatureBuilder extends AbstractSignatureBu
      * @param certifiedKey key ring
      * @param userAttribute user-attributes to certify
      * @return signature
+     *
+     * @throws PGPException if the signature generator cannot be initialized
      */
     public PGPSignature build(PGPPublicKeyRing certifiedKey, PGPUserAttributeSubpacketVector userAttribute)
             throws PGPException {

pgpainless-core/src/main/java/org/pgpainless/signature/consumer/SignaturePicker.java

@@ -43,6 +43,8 @@ public final class SignaturePicker {
      * validationDate or if it is already expired.
      *
      * @param keyRing key ring
+     * @param policy policy
+     * @param validationDate date of signature validation
      * @return most recent, valid key revocation signature
      */
     public static PGPSignature pickCurrentRevocationSelfSignature(PGPKeyRing keyRing, Policy policy, Date validationDate) {
@@ -69,6 +71,7 @@ public final class SignaturePicker {
      * This method might return null, if there is no direct key self-signature which is valid at validationDate.
      *
      * @param keyRing key ring
+     * @param policy policy
      * @param validationDate validation date
      * @return direct-key self-signature
      */
@@ -83,6 +86,7 @@ public final class SignaturePicker {
      *
      * @param signingKey key that created the signature
      * @param signedKey key that carries the signature
+     * @param policy policy
      * @param validationDate validation date
      * @return direct key sig
      */
@@ -110,6 +114,7 @@ public final class SignaturePicker {
      * yet already effective direct-key signature will be returned.
      *
      * @param keyRing key ring
+     * @param policy policy
      * @param validationDate validation date
      * @return latest direct key signature
      */
@@ -126,6 +131,7 @@ public final class SignaturePicker {
      *
      * @param signingKey signing key (key that made the sig)
      * @param signedKey signed key (key that carries the sig)
+     * @param policy policy
      * @param validationDate date of validation
      * @return latest direct key sig
      */
@@ -160,6 +166,7 @@ public final class SignaturePicker {
      *
      * @param keyRing key ring
      * @param userId user-Id that gets revoked
+     * @param policy policy
      * @param validationDate validation date
      * @return revocation signature
      */
@@ -193,6 +200,7 @@ public final class SignaturePicker {
      *
      * @param keyRing keyring
      * @param userId userid
+     * @param policy policy
      * @param validationDate validation date
      * @return user-id certification
      */
@@ -225,6 +233,7 @@ public final class SignaturePicker {
      *
      * @param keyRing keyring
      * @param userId userid
+     * @param policy policy
      * @param validationDate validation date
      * @return user-id certification
      */
@@ -261,6 +270,7 @@ public final class SignaturePicker {
      *
      * @param keyRing keyring
      * @param subkey subkey
+     * @param policy policy
      * @param validationDate validation date
      * @return subkey revocation signature
      */
@@ -293,6 +303,7 @@ public final class SignaturePicker {
      *
      * @param keyRing key ring
      * @param subkey subkey
+     * @param policy policy
      * @param validationDate date of validation
      * @return most recent valid subkey binding signature
      */
@@ -326,6 +337,7 @@ public final class SignaturePicker {
      *
      * @param keyRing key ring
      * @param subkey subkey
+     * @param policy policy
      * @param validationDate validationDate
      * @return subkey binding signature
      */

pgpainless-core/src/main/java/org/pgpainless/signature/consumer/SignatureValidityComparator.java

@@ -31,6 +31,8 @@ public class SignatureValidityComparator implements Comparator<PGPSignature> {
     /**
      * Create a new {@link SignatureValidityComparator} which orders signatures following the passed ordering.
      * Still, hard revocations will come first.
+     *
+     * @param order order of creation dates
      */
     public SignatureValidityComparator(SignatureCreationDateComparator.Order order) {
         this.creationDateComparator = new SignatureCreationDateComparator(order);

pgpainless-core/src/main/java/org/pgpainless/signature/subpackets/SignatureSubpacketsUtil.java

@@ -506,6 +506,8 @@ public final class SignatureSubpacketsUtil {
      *
      * @param signature signature
      * @return embedded signature
+     *
+     * @throws PGPException in case the embedded signatures cannot be parsed
      */
     public static PGPSignatureList getEmbeddedSignature(PGPSignature signature) throws PGPException {
         PGPSignatureList hashed = signature.getHashedSubPackets().getEmbeddedSignatures();

pgpainless-core/src/main/java/org/pgpainless/util/ArmorUtils.java

@@ -544,6 +544,8 @@ public final class ArmorUtils {
      *
      * @param inputStream input stream
      * @return BufferedInputStreamExt
+     *
+     * @throws IOException in case of an IO error
      */
     @Nonnull
     public static InputStream getDecoderStream(@Nonnull InputStream inputStream)