wrapped-key-ring: add documentation

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;