Document various KeyRingSelectionStrategies

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

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) {

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

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;

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() {

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