wrapped-key-ring: add documentation

1 files changed, 16 insertions, 0 deletions

diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/provider/CachedPublicKeyRing.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/provider/CachedPublicKeyRing.java
index ed1988336..48d40430a 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/provider/CachedPublicKeyRing.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/provider/CachedPublicKeyRing.java
@@ -7,6 +7,22 @@ import org.sufficientlysecure.keychain.pgp.KeyRing;
 import org.sufficientlysecure.keychain.pgp.exception.PgpGeneralException;
 import org.sufficientlysecure.keychain.util.Log;
 
+/** This implementation of KeyRing provides a cached view of PublicKeyRing
+ * objects based on database queries exclusively.
+ *
+ * This class should be used where only few points of data but no actual
+ * cryptographic operations are required about a PublicKeyRing which is already
+ * in the database.  This happens commonly in UI code, where parsing of a PGP
+ * key for examination would be a very expensive operation.
+ *
+ * Each getter method is implemented using a more or less expensive database
+ * query, while object construction is (almost) free. A common pattern is
+ * mProviderHelper.getCachedKeyRing(uri).getterMethod()
+ *
+ * TODO Ensure that the values returned here always match the ones returned by
+ * the parsed KeyRing!
+ *
+ */
 public class CachedPublicKeyRing extends KeyRing {
 
     final ProviderHelper mProviderHelper;