Add documentation to classes related to verification of cleartext signed data

pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/InMemoryMultiPassStrategy.java

@@ -18,6 +18,14 @@ package org.pgpainless.signature.cleartext_signatures;
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 
+/**
+ * Implementation of the {@link MultiPassStrategy}.
+ * This class keeps the read data in memory by caching the data inside a {@link ByteArrayOutputStream}.
+ *
+ * Note, that this class is suitable and efficient for processing small amounts of data.
+ * For larger data like encrypted files, use of the {@link WriteToFileMultiPassStrategy} is recommended to
+ * prevent {@link OutOfMemoryError OutOfMemoryErrors} and other issues.
+ */
 public class InMemoryMultiPassStrategy implements MultiPassStrategy {
 
     private final ByteArrayOutputStream cache = new ByteArrayOutputStream();
@@ -29,7 +37,7 @@ public class InMemoryMultiPassStrategy implements MultiPassStrategy {
 
     @Override
     public ByteArrayInputStream getMessageInputStream() {
-        return new ByteArrayInputStream(cache.toByteArray());
+        return new ByteArrayInputStream(getBytes());
     }
 
     public byte[] getBytes() {

pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/MultiPassStrategy.java

@@ -22,7 +22,11 @@ import java.io.InputStream;
 import java.io.OutputStream;
 
 /**
- * Interface that describes a strategy to deal with the fact that detached signatures require multiple passes
+ * Since the {@link CleartextSignatureProcessor} needs to read the whole data twice in order to verify signatures,
+ * a strategy for how to cache the read data is required.
+ * Otherwise large data kept in memory could cause {@link OutOfMemoryError OutOfMemoryErrors} or other issues.
+ *
+ * This is an Interface that describes a strategy to deal with the fact that detached signatures require multiple passes
  * to do verification.
  *
  * This interface can be used to write the signed data stream out via {@link #getMessageOutputStream()} and later

pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/VerifyCleartextSignatures.java

@@ -23,6 +23,9 @@ import org.bouncycastle.openpgp.PGPException;
 import org.bouncycastle.openpgp.PGPPublicKeyRing;
 import org.bouncycastle.openpgp.PGPPublicKeyRingCollection;
 
+/**
+ * Interface defining the API for verification of cleartext signed documents.
+ */
 public interface VerifyCleartextSignatures {
 
     /**

pgpainless-core/src/main/java/org/pgpainless/signature/cleartext_signatures/WriteToFileMultiPassStrategy.java

@@ -23,9 +23,12 @@ import java.io.InputStream;
 import java.io.OutputStream;
 
 /**
- * File-based multi-pass strategy.
- * When processing the signed data the first time, the data is being written out into a file.
+ * Implementation of the {@link MultiPassStrategy}.
+ * When processing signed data the first time, the data is being written out into a file.
  * For the second pass, that file is being read again.
+ *
+ * This strategy is recommended when larger amounts of data need to be processed.
+ * For smaller files, {@link InMemoryMultiPassStrategy} yields higher efficiency.
  */
 public class WriteToFileMultiPassStrategy implements MultiPassStrategy {