From 2c86d8dfe45089d1c02b9b8383c90afaa4c51fe5 Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Mon, 4 Apr 2022 12:49:00 +0200
Subject: [PATCH] Document various KeyRingSelectionStrategies

---
 .../PublicKeyRingSelectionStrategy.java       |  5 +++++
 .../SecretKeyRingSelectionStrategy.java       |  6 +++++
 .../selection/keyring/impl/ExactUserId.java   | 12 ++++++++++
 .../selection/keyring/impl/Whitelist.java     | 22 +++++++++++++++++++
 .../util/selection/keyring/impl/Wildcard.java |  3 +++
 .../util/selection/keyring/impl/XMPP.java     | 16 ++++++++++++++
 6 files changed, 64 insertions(+)

diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/PublicKeyRingSelectionStrategy.java b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/PublicKeyRingSelectionStrategy.java
index 038549bf..68c9d946 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/PublicKeyRingSelectionStrategy.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/PublicKeyRingSelectionStrategy.java
@@ -13,6 +13,11 @@ import org.bouncycastle.openpgp.PGPPublicKeyRing;
 import org.bouncycastle.openpgp.PGPPublicKeyRingCollection;
 import org.pgpainless.util.MultiMap;
 
+/**
+ * Abstract {@link KeyRingSelectionStrategy} for {@link PGPPublicKeyRing PGPPublicKeyRings}.
+ *
+ * @param <O> Type of identifier
+ */
 public abstract class PublicKeyRingSelectionStrategy<O> implements KeyRingSelectionStrategy<PGPPublicKeyRing, PGPPublicKeyRingCollection, O> {
 
     @Override
diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/SecretKeyRingSelectionStrategy.java b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/SecretKeyRingSelectionStrategy.java
index c54f81a5..943f2d82 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/SecretKeyRingSelectionStrategy.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/SecretKeyRingSelectionStrategy.java
@@ -9,10 +9,16 @@ import java.util.HashSet;
 import java.util.Iterator;
 import java.util.Set;
 
+import org.bouncycastle.openpgp.PGPPublicKeyRing;
 import org.bouncycastle.openpgp.PGPSecretKeyRing;
 import org.bouncycastle.openpgp.PGPSecretKeyRingCollection;
 import org.pgpainless.util.MultiMap;
 
+/**
+ * Abstract {@link KeyRingSelectionStrategy} for {@link PGPSecretKeyRing PGPSecretKeyRings}.
+ *
+ * @param <O> Type of identifier
+ */
 public abstract class SecretKeyRingSelectionStrategy<O> implements KeyRingSelectionStrategy<PGPSecretKeyRing, PGPSecretKeyRingCollection, O> {
     @Override
     public Set<PGPSecretKeyRing> selectKeyRingsFromCollection(O identifier, @Nonnull PGPSecretKeyRingCollection keyRingCollection) {
diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/ExactUserId.java b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/ExactUserId.java
index 5a05dc56..29c43c41 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/ExactUserId.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/ExactUserId.java
@@ -11,12 +11,20 @@ import org.bouncycastle.openpgp.PGPSecretKeyRing;
 import org.pgpainless.util.selection.keyring.PublicKeyRingSelectionStrategy;
 import org.pgpainless.util.selection.keyring.SecretKeyRingSelectionStrategy;
 
+/**
+ * Implementations of {@link org.pgpainless.util.selection.keyring.KeyRingSelectionStrategy} which select key rings
+ * based on the exact user-id.
+ */
 public final class ExactUserId {
 
     private ExactUserId() {
 
     }
 
+    /**
+     * {@link PublicKeyRingSelectionStrategy} which accepts {@link PGPPublicKeyRing PGPPublicKeyRings} if those
+     * have a user-id which exactly matches the given <pre>identifier</pre>.
+     */
     public static class PubRingSelectionStrategy extends PublicKeyRingSelectionStrategy<String> {
 
         @Override
@@ -29,6 +37,10 @@ public final class ExactUserId {
         }
     }
 
+    /**
+     * {@link SecretKeyRingSelectionStrategy} which accepts {@link PGPSecretKeyRing PGPSecretKeyRings} if those
+     * have a user-id which exactly matches the given <pre>identifier</pre>.
+     */
     public static class SecRingSelectionStrategy extends SecretKeyRingSelectionStrategy<String> {
 
         @Override
diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Whitelist.java b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Whitelist.java
index f296d8f1..934f5577 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Whitelist.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Whitelist.java
@@ -13,12 +13,25 @@ import org.pgpainless.util.selection.keyring.PublicKeyRingSelectionStrategy;
 import org.pgpainless.util.selection.keyring.SecretKeyRingSelectionStrategy;
 import org.pgpainless.util.MultiMap;
 
+/**
+ * Implementations of {@link org.pgpainless.util.selection.keyring.KeyRingSelectionStrategy} which accept PGP KeyRings
+ * based on a whitelist of acceptable keyIds.
+ */
 public final class Whitelist {
 
     private Whitelist() {
 
     }
 
+    /**
+     * {@link org.pgpainless.util.selection.keyring.KeyRingSelectionStrategy} which accepts
+     * {@link PGPPublicKeyRing PGPPublicKeyRings} if the <pre>whitelist</pre> contains their primary key id.
+     *
+     * If the whitelist contains 123L for "alice@pgpainless.org", the key with primary key id 123L is
+     * acceptable for "alice@pgpainless.org".
+     *
+     * @param <O> Type of identifier for {@link org.bouncycastle.openpgp.PGPPublicKeyRingCollection PGPPublicKeyRingCollections}.
+     */
     public static class PubRingSelectionStrategy<O> extends PublicKeyRingSelectionStrategy<O> {
 
         private final MultiMap<O, Long> whitelist;
@@ -43,6 +56,15 @@ public final class Whitelist {
         }
     }
 
+    /**
+     * {@link org.pgpainless.util.selection.keyring.KeyRingSelectionStrategy} which accepts
+     * {@link PGPSecretKeyRing PGPSecretKeyRings} if the <pre>whitelist</pre> contains their primary key id.
+     *
+     * If the whitelist contains 123L for "alice@pgpainless.org", the key with primary key id 123L is
+     * acceptable for "alice@pgpainless.org".
+     *
+     * @param <O> Type of identifier for {@link org.bouncycastle.openpgp.PGPSecretKeyRingCollection PGPSecretKeyRingCollections}.
+     */
     public static class SecRingSelectionStrategy<O> extends SecretKeyRingSelectionStrategy<O> {
 
         private final MultiMap<O, Long> whitelist;
diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Wildcard.java b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Wildcard.java
index f7bab777..d1929028 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Wildcard.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/Wildcard.java
@@ -9,6 +9,9 @@ import org.bouncycastle.openpgp.PGPSecretKeyRing;
 import org.pgpainless.util.selection.keyring.PublicKeyRingSelectionStrategy;
 import org.pgpainless.util.selection.keyring.SecretKeyRingSelectionStrategy;
 
+/**
+ * Implementations of {@link org.pgpainless.util.selection.keyring.KeyRingSelectionStrategy} which accept all keyRings.
+ */
 public final class Wildcard {
 
     private Wildcard() {
diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/XMPP.java b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/XMPP.java
index 11c3c8ff..edc38006 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/XMPP.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/impl/XMPP.java
@@ -7,12 +7,22 @@ package org.pgpainless.util.selection.keyring.impl;
 import org.bouncycastle.openpgp.PGPPublicKeyRing;
 import org.bouncycastle.openpgp.PGPSecretKeyRing;
 
+/**
+ * Implementations of {@link org.pgpainless.util.selection.keyring.KeyRingSelectionStrategy} which accept KeyRings
+ * containing a given XMPP address of the format "xmpp:alice@pgpainless.org".
+ */
 public final class XMPP {
 
     private XMPP() {
 
     }
 
+    /**
+     * {@link org.pgpainless.util.selection.keyring.PublicKeyRingSelectionStrategy} which accepts a given
+     * {@link PGPPublicKeyRing} if its primary key has a user-id that matches the given <pre>jid</pre>.
+     *
+     * The argument <pre>jid</pre> can either contain the prefix "xmpp:", or not, the result will be the same.
+     */
     public static class PubRingSelectionStrategy extends ExactUserId.PubRingSelectionStrategy {
 
         @Override
@@ -24,6 +34,12 @@ public final class XMPP {
         }
     }
 
+    /**
+     * {@link org.pgpainless.util.selection.keyring.SecretKeyRingSelectionStrategy} which accepts a given
+     * {@link PGPSecretKeyRing} if its primary key has a user-id that matches the given <pre>jid</pre>.
+     *
+     * The argument <pre>jid</pre> can either contain the prefix "xmpp:", or not, the result will be the same.
+     */
     public static class SecRingSelectionStrategy extends ExactUserId.SecRingSelectionStrategy {
 
         @Override