From 405e67c0cbcd1448dbb87d7dadef589e65cced2c Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Mon, 29 Aug 2022 11:06:17 +0200
Subject: [PATCH] Add documentation to AlgorithmNegotiator classes

---
 .../negotiation/HashAlgorithmNegotiator.java  | 33 +++++++++++++++++++
 .../SymmetricKeyAlgorithmNegotiator.java      | 21 ++++++++++--
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/HashAlgorithmNegotiator.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/HashAlgorithmNegotiator.java
index f76a2c26..18fe53f9 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/HashAlgorithmNegotiator.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/HashAlgorithmNegotiator.java
@@ -9,18 +9,51 @@ import java.util.Set;
 import org.pgpainless.algorithm.HashAlgorithm;
 import org.pgpainless.policy.Policy;
 
+/**
+ * Interface for a class that negotiates {@link HashAlgorithm HashAlgorithms}.
+ *
+ * You can provide your own implementation using custom logic by implementing the
+ * {@link #negotiateHashAlgorithm(Set)} method.
+ */
 public interface HashAlgorithmNegotiator {
 
+    /**
+     * Pick one {@link HashAlgorithm} from the ordered set of acceptable algorithms.
+     *
+     * @param orderedHashAlgorithmPreferencesSet hash algorithm preferences
+     * @return picked algorithms
+     */
     HashAlgorithm negotiateHashAlgorithm(Set<HashAlgorithm> orderedHashAlgorithmPreferencesSet);
 
+    /**
+     * Return an instance that negotiates {@link HashAlgorithm HashAlgorithms} used for non-revocation signatures
+     * based on the given {@link Policy}.
+     *
+     * @param policy algorithm policy
+     * @return negotiator
+     */
     static HashAlgorithmNegotiator negotiateSignatureHashAlgorithm(Policy policy) {
         return negotiateByPolicy(policy.getSignatureHashAlgorithmPolicy());
     }
 
+    /**
+     * Return an instance that negotiates {@link HashAlgorithm HashAlgorithms} used for revocation signatures
+     * based on the given {@link Policy}.
+     *
+     * @param policy algorithm policy
+     * @return negotiator
+     */
     static HashAlgorithmNegotiator negotiateRevocationSignatureAlgorithm(Policy policy) {
         return negotiateByPolicy(policy.getRevocationSignatureHashAlgorithmPolicy());
     }
 
+    /**
+     * Return an instance that negotiates {@link HashAlgorithm HashAlgorithms} based on the given
+     * {@link Policy.HashAlgorithmPolicy}.
+     *
+     * @param hashAlgorithmPolicy algorithm policy for hash algorithms
+     * @return negotiator
+     */
     static HashAlgorithmNegotiator negotiateByPolicy(Policy.HashAlgorithmPolicy hashAlgorithmPolicy) {
         return new HashAlgorithmNegotiator() {
             @Override
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/SymmetricKeyAlgorithmNegotiator.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/SymmetricKeyAlgorithmNegotiator.java
index 427bcc69..de8ced24 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/SymmetricKeyAlgorithmNegotiator.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/negotiation/SymmetricKeyAlgorithmNegotiator.java
@@ -22,18 +22,35 @@ public interface SymmetricKeyAlgorithmNegotiator {
 
     /**
      * Negotiate a symmetric encryption algorithm.
+     * If the override is non-null, it will be returned instead of performing an actual negotiation.
+     * Otherwise, the list of ordered sets containing the preferences of different recipient keys will be
+     * used to determine a suitable symmetric encryption algorithm.
      *
      * @param policy algorithm policy
      * @param override algorithm override (if not null, return this)
      * @param keyPreferences list of preferences per key
      * @return negotiated algorithm
      */
-    SymmetricKeyAlgorithm negotiate(Policy.SymmetricKeyAlgorithmPolicy policy, SymmetricKeyAlgorithm override, List<Set<SymmetricKeyAlgorithm>> keyPreferences);
+    SymmetricKeyAlgorithm negotiate(
+            Policy.SymmetricKeyAlgorithmPolicy policy,
+            SymmetricKeyAlgorithm override,
+            List<Set<SymmetricKeyAlgorithm>> keyPreferences);
 
+    /**
+     * Return an instance that negotiates a {@link SymmetricKeyAlgorithm} by selecting the most popular acceptable
+     * algorithm from the list of preferences.
+     *
+     * This negotiator has the best chances to select an algorithm which is understood by all recipients.
+     *
+     * @return negotiator that selects by popularity
+     */
     static SymmetricKeyAlgorithmNegotiator byPopularity() {
         return new SymmetricKeyAlgorithmNegotiator() {
             @Override
-            public SymmetricKeyAlgorithm negotiate(Policy.SymmetricKeyAlgorithmPolicy policy, SymmetricKeyAlgorithm override, List<Set<SymmetricKeyAlgorithm>> preferences) {
+            public SymmetricKeyAlgorithm negotiate(
+                    Policy.SymmetricKeyAlgorithmPolicy policy,
+                    SymmetricKeyAlgorithm override,
+                    List<Set<SymmetricKeyAlgorithm>> preferences) {
                 if (override == SymmetricKeyAlgorithm.NULL) {
                     throw new IllegalArgumentException("Algorithm override cannot be NULL (plaintext).");
                 }