From 9812d4d78c8c044f96a386478f7535fa950aec22 Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Fri, 28 Feb 2025 14:13:48 +0100
Subject: [PATCH] Add some missing documentation to ConsumerOptions

---
 .../decryption_verification/ConsumerOptions.kt   | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt b/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt
index 55c781ae..5606d10f 100644
--- a/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt
+++ b/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt
@@ -417,6 +417,7 @@ class ConsumerOptions {
          * @param certificate certificate
          */
         @JvmOverloads
+        @Deprecated("Pass in an OpenPGPCertificate instead.")
         fun addCertificate(
             certificate: PGPPublicKeyRing,
             implementation: OpenPGPImplementation = PGPainless.getInstance().implementation
@@ -424,6 +425,11 @@ class ConsumerOptions {
             explicitCertificates.add(OpenPGPCertificate(certificate, implementation))
         }
 
+        /**
+         * Add a certificate as explicitly provided verification cert.
+         *
+         * @param certificate explicit verification cert
+         */
         fun addCertificate(certificate: OpenPGPCertificate) {
             explicitCertificates.add(certificate)
         }
@@ -445,14 +451,24 @@ class ConsumerOptions {
          * @param keyId key id
          * @return certificate
          */
+        @Deprecated("Pass in a KeyIdentifier instead.")
         fun getCertificate(keyId: Long): OpenPGPCertificate? {
             return getCertificate(KeyIdentifier(keyId))
         }
 
+        /**
+         * Return a certificate which contains a component key for the given [identifier]. This
+         * method first checks all explicitly provided verification certs and if no cert is found it
+         * consults the certificate stores.
+         *
+         * @param identifier key identifier
+         * @return certificate or null if no match is found
+         */
         fun getCertificate(identifier: KeyIdentifier): OpenPGPCertificate? {
             return explicitCertificates.firstOrNull { it.getKey(identifier) != null }
         }
 
+        /** Find a certificate containing the issuer component key for the given [signature]. */
         fun getCertificate(signature: PGPSignature): OpenPGPCertificate? =
             explicitCertificates.firstOrNull { it.getSigningKeyFor(signature) != null }
     }