From dc0b96278e4f7fcec8bc60df0386360194052fcd Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Mon, 18 Oct 2021 16:19:12 +0200
Subject: [PATCH] Add javadoc

---
 .../ConsumerOptions.java                      | 27 +++++++++++++++++++
 .../MissingKeyPassphraseStrategy.java         | 15 +++++++++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java
index f5be25bd..3c1a9454 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/ConsumerOptions.java
@@ -225,6 +225,9 @@ public class ConsumerOptions {
 
     /**
      * Add a passphrase for message decryption.
+     * This passphrase will be used to try to decrypt messages which were symmetrically encrypted for a passphrase.
+     *
+     * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.7">Symmetrically Encrypted Data Packet</a>
      *
      * @param passphrase passphrase
      * @return options
@@ -288,15 +291,39 @@ public class ConsumerOptions {
         return this;
     }
 
+    /**
+     * Return true, if PGPainless is ignoring MDC errors.
+     *
+     * @return ignore mdc errors
+     */
     boolean isIgnoreMDCErrors() {
         return ignoreMDCErrors;
     }
 
+    /**
+     * Specify the {@link MissingKeyPassphraseStrategy}.
+     * This strategy defines, how missing passphrases for unlocking secret keys are handled.
+     * In interactive mode ({@link MissingKeyPassphraseStrategy#INTERACTIVE}) PGPainless will try to obtain missing
+     * passphrases for secret keys via the {@link SecretKeyRingProtector SecretKeyRingProtectors}
+     * {@link org.pgpainless.key.protection.passphrase_provider.SecretKeyPassphraseProvider} callback.
+     *
+     * In non-interactice mode ({@link MissingKeyPassphraseStrategy#THROW_EXCEPTION}, PGPainless will instead
+     * throw a {@link org.pgpainless.exception.MissingPassphraseException} containing the ids of all keys for which
+     * there are missing passphrases.
+     *
+     * @param strategy strategy
+     * @return options
+     */
     public ConsumerOptions setMissingKeyPassphraseStrategy(MissingKeyPassphraseStrategy strategy) {
         this.missingKeyPassphraseStrategy = strategy;
         return this;
     }
 
+    /**
+     * Return the currently configured {@link MissingKeyPassphraseStrategy}.
+     *
+     * @return missing key passphrase strategy
+     */
     MissingKeyPassphraseStrategy getMissingKeyPassphraseStrategy() {
         return missingKeyPassphraseStrategy;
     }
diff --git a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MissingKeyPassphraseStrategy.java b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MissingKeyPassphraseStrategy.java
index 166f954b..ed6a9c63 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MissingKeyPassphraseStrategy.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/decryption_verification/MissingKeyPassphraseStrategy.java
@@ -4,7 +4,18 @@
 
 package org.pgpainless.decryption_verification;
 
+/**
+ * Strategy defining how missing secret key passphrases are handled.
+ */
 public enum MissingKeyPassphraseStrategy {
-    INTERACTIVE, // ask for missing key passphrases one by one
-    THROW_EXCEPTION // throw an exception with all keys with missing passphrases
+    /**
+     * Try to interactively obtain key passphrases one-by-one via callbacks,
+     * eg {@link org.pgpainless.key.protection.passphrase_provider.SecretKeyPassphraseProvider}.
+     */
+    INTERACTIVE,
+    /**
+     * Do not try to obtain passphrases interactively and instead throw a
+     * {@link org.pgpainless.exception.MissingPassphraseException} listing all keys with missing passphrases.
+     */
+    THROW_EXCEPTION
 }