Add missing javadoc to ConsumerOptions

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

@@ -42,7 +42,6 @@ import pgp.certificate_store.exception.BadDataException;
  */
 public class ConsumerOptions {
 
-
     private boolean ignoreMDCErrors = false;
     private boolean forceNonOpenPgpData = false;
 
@@ -55,7 +54,8 @@ public class ConsumerOptions {
 
     // Session key for decryption without passphrase/key
     private SessionKey sessionKey = null;
-    private final Map<SubkeyIdentifier, PublicKeyDataDecryptorFactory> customPublicKeyDataDecryptorFactories = new HashMap<>();
+    private final Map<SubkeyIdentifier, PublicKeyDataDecryptorFactory> customPublicKeyDataDecryptorFactories =
+            new HashMap<>();
 
     private final Map<PGPSecretKeyRing, SecretKeyRingProtector> decryptionKeys = new HashMap<>();
     private final Set<Passphrase> decryptionPassphrases = new HashSet<>();
@@ -135,16 +135,38 @@ public class ConsumerOptions {
         return this;
     }
 
+    /**
+     * Pass in a {@link PGPCertificateStore} from which certificates can be sourced for signature verification.
+     *
+     * @param certificateStore certificate store
+     * @return options
+     */
     public ConsumerOptions addVerificationCerts(PGPCertificateStore certificateStore) {
         this.certificates.addStore(certificateStore);
         return this;
     }
 
-    public ConsumerOptions addVerificationOfDetachedSignatures(InputStream signatureInputStream) throws IOException, PGPException {
+    /**
+     * Add some detached signatures from the given {@link InputStream} for verification.
+     *
+     * @param signatureInputStream input stream of detached signatures
+     * @return options
+     *
+     * @throws IOException in case of an IO error
+     * @throws PGPException in case of an OpenPGP error
+     */
+    public ConsumerOptions addVerificationOfDetachedSignatures(InputStream signatureInputStream)
+            throws IOException, PGPException {
         List<PGPSignature> signatures = SignatureUtils.readSignatures(signatureInputStream);
         return addVerificationOfDetachedSignatures(signatures);
     }
 
+    /**
+     * Add some detached signatures for verification.
+     *
+     * @param detachedSignatures detached signatures
+     * @return options
+     */
     public ConsumerOptions addVerificationOfDetachedSignatures(List<PGPSignature> detachedSignatures) {
         for (PGPSignature signature : detachedSignatures) {
             addVerificationOfDetachedSignature(signature);
@@ -211,14 +233,15 @@ public class ConsumerOptions {
     }
 
     /**
-     * Add a key for message decryption. If the key is encrypted, the {@link SecretKeyRingProtector} is used to decrypt it
+     * Add a key for message decryption. If the key is encrypted, the {@link SecretKeyRingProtector}
-     * when needed.
+     * is used to decrypt it when needed.
      *
      * @param key key
      * @param keyRingProtector protector for the secret key
      * @return options
      */
-    public ConsumerOptions addDecryptionKey(@Nonnull PGPSecretKeyRing key, @Nonnull SecretKeyRingProtector keyRingProtector) {
+    public ConsumerOptions addDecryptionKey(@Nonnull PGPSecretKeyRing key,
+                                            @Nonnull SecretKeyRingProtector keyRingProtector) {
         decryptionKeys.put(key, keyRingProtector);
         return this;
     }
@@ -230,7 +253,8 @@ public class ConsumerOptions {
      * @param keyRingProtector protector for encrypted secret keys
      * @return options
      */
-    public ConsumerOptions addDecryptionKeys(@Nonnull PGPSecretKeyRingCollection keys, @Nonnull SecretKeyRingProtector keyRingProtector) {
+    public ConsumerOptions addDecryptionKeys(@Nonnull PGPSecretKeyRingCollection keys,
+                                             @Nonnull SecretKeyRingProtector keyRingProtector) {
         for (PGPSecretKeyRing key : keys) {
             addDecryptionKey(key, keyRingProtector);
         }
@@ -264,14 +288,31 @@ public class ConsumerOptions {
         return this;
     }
 
+    /**
+     * Return the custom {@link PublicKeyDataDecryptorFactory PublicKeyDataDecryptorFactories} that were
+     * set by the user.
+     * These factories can be used to decrypt session keys using a custom logic.
+     *
+     * @return custom decryptor factories
+     */
     Map<SubkeyIdentifier, PublicKeyDataDecryptorFactory> getCustomDecryptorFactories() {
         return new HashMap<>(customPublicKeyDataDecryptorFactories);
     }
 
+    /**
+     * Return the set of available decryption keys.
+     *
+     * @return decryption keys
+     */
     public @Nonnull Set<PGPSecretKeyRing> getDecryptionKeys() {
         return Collections.unmodifiableSet(decryptionKeys.keySet());
     }
 
+    /**
+     * Return the set of available message decryption passphrases.
+     *
+     * @return decryption passphrases
+     */
     public @Nonnull Set<Passphrase> getDecryptionPassphrases() {
         return Collections.unmodifiableSet(decryptionPassphrases);
     }
@@ -287,18 +328,40 @@ public class ConsumerOptions {
         return certificates.getExplicitCertificates();
     }
 
+    /**
+     * Return an object holding available certificates for signature verification.
+     *
+     * @return certificate source
+     */
     public @Nonnull CertificateSource getCertificateSource() {
         return certificates;
     }
 
+    /**
+     * Return the callback that gets called when a certificate for signature verification is missing.
+     * This method might return <pre>null</pre> if the users hasn't set a callback.
+     *
+     * @return missing public key callback
+     */
     public @Nullable MissingPublicKeyCallback getMissingCertificateCallback() {
         return missingCertificateCallback;
     }
 
+    /**
+     * Return the {@link SecretKeyRingProtector} for the given {@link PGPSecretKeyRing}.
+     *
+     * @param decryptionKeyRing secret key
+     * @return protector for that particular secret key
+     */
     public @Nonnull SecretKeyRingProtector getSecretKeyProtector(PGPSecretKeyRing decryptionKeyRing) {
         return decryptionKeys.get(decryptionKeyRing);
     }
 
+    /**
+     * Return the set of detached signatures the user provided.
+     *
+     * @return detached signatures
+     */
     public @Nonnull Set<PGPSignature> getDetachedSignatures() {
         return Collections.unmodifiableSet(detachedSignatures);
     }
@@ -307,12 +370,14 @@ public class ConsumerOptions {
      * By default, PGPainless will require encrypted messages to make use of SEIP data packets.
      * Those are Symmetrically Encrypted Integrity Protected Data packets.
      * Symmetrically Encrypted Data Packets without integrity protection are rejected by default.
-     * Furthermore, PGPainless will throw an exception if verification of the MDC error detection code of the SEIP packet
+     * Furthermore, PGPainless will throw an exception if verification of the MDC error detection
-     * fails.
+     * code of the SEIP packet fails.
      *
-     * Failure of MDC verification indicates a tampered ciphertext, which might be the cause of an attack or data corruption.
+     * Failure of MDC verification indicates a tampered ciphertext, which might be the cause of an
+     * attack or data corruption.
      *
-     * This method can be used to ignore MDC errors and allow PGPainless to consume encrypted data without integrity protection.
+     * This method can be used to ignore MDC errors and allow PGPainless to consume encrypted data
+     * without integrity protection.
      * If the flag <pre>ignoreMDCErrors</pre> is set to true, PGPainless will
      * <ul>
      *     <li>not throw exceptions for SEIP packets with tampered ciphertext</li>
@@ -323,7 +388,8 @@ public class ConsumerOptions {
      *
      * It will however still throw an exception if it encounters a SEIP packet with missing or truncated MDC
      *
-     * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.13">Sym. Encrypted Integrity Protected Data Packet</a>
+     * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.13">
+     *     Sym. Encrypted Integrity Protected Data Packet</a>
      * @param ignoreMDCErrors true if MDC errors or missing MDCs shall be ignored, false otherwise.
      * @return options
      */
@@ -353,6 +419,11 @@ public class ConsumerOptions {
         return this;
     }
 
+    /**
+     * Return true, if the ciphertext should be handled as binary non-OpenPGP data.
+     *
+     * @return true if non-OpenPGP data is forced
+     */
     boolean isForceNonOpenPgpData() {
         return forceNonOpenPgpData;
     }
@@ -407,6 +478,10 @@ public class ConsumerOptions {
         return multiPassStrategy;
     }
 
+    /**
+     * Source for OpenPGP certificates.
+     * When verifying signatures on a message, this object holds available signer certificates.
+     */
     public static class CertificateSource {
 
         private List<PGPCertificateStore> stores = new ArrayList<>();