From 7ca9934cbe08ae0648f73d34e31b0a6f532577ce Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Mon, 4 Apr 2022 12:32:37 +0200
Subject: [PATCH] Document KeyRingSelectionStrategy

---
 .../keyring/KeyRingSelectionStrategy.java     | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/KeyRingSelectionStrategy.java b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/KeyRingSelectionStrategy.java
index a9f842e3..fb57e338 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/KeyRingSelectionStrategy.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/util/selection/keyring/KeyRingSelectionStrategy.java
@@ -8,11 +8,41 @@ import java.util.Set;
 
 import org.pgpainless.util.MultiMap;
 
+/**
+ *
+ * @param <R> Type of {@link org.bouncycastle.openpgp.PGPKeyRing} ({@link org.bouncycastle.openpgp.PGPSecretKeyRing}
+ *           or {@link org.bouncycastle.openpgp.PGPPublicKeyRing}).
+ * @param <C> Type of key ring collection (e.g. {@link org.bouncycastle.openpgp.PGPSecretKeyRingCollection}
+ *          or {@link org.bouncycastle.openpgp.PGPPublicKeyRingCollection}).
+ * @param <O> Type of key identifier
+ */
 public interface KeyRingSelectionStrategy<R, C, O> {
 
+    /**
+     * Return true, if the filter accepts the given <pre>keyRing</pre> based on the given <pre>identifier</pre>.
+     *
+     * @param identifier identifier
+     * @param keyRing key ring
+     * @return acceptance
+     */
     boolean accept(O identifier, R keyRing);
 
+    /**
+     * Iterate of the given <pre>keyRingCollection</pre> and return a {@link Set} of all acceptable
+     * keyRings in the collection, based on the given <pre>identifier</pre>.
+     *
+     * @param identifier identifier
+     * @param keyRingCollection collection
+     * @return set of acceptable key rings
+     */
     Set<R> selectKeyRingsFromCollection(O identifier, C keyRingCollection);
 
+    /**
+     * Iterate over all keyRings in the given {@link MultiMap} of keyRingCollections and return a new {@link MultiMap}
+     * which for every identifier (key of the map) contains all acceptable keyRings based on that identifier.
+     *
+     * @param keyRingCollections MultiMap of identifiers and keyRingCollections.
+     * @return MultiMap of identifiers and acceptable keyRings.
+     */
     MultiMap<O, R> selectKeyRingsFromCollections(MultiMap<O, C> keyRingCollections);
 }