docs(cache): improve CacheEntry and Cache interface documentation

Author: wobondar

pkg/materials/cache/memory_cache.go

@@ -71,7 +71,7 @@ func (m *MemoryCache) PutDecryptionEntry(key string, dm model.DecryptionMaterial
 	return m.storeCacheEntry(key, entry)
 }
 
-// GetEncryptionEntry retrieves a encryption entry from the cache using a specified key.
+// GetEncryptionEntry retrieves an encryption entry from the cache using a specified key.
 // It updates the metadata with the provided number of bytes.
 // Returns the cache entry and a boolean indicating success.
 func (m *MemoryCache) GetEncryptionEntry(key string, n int) (model.CacheEntry, bool) {

pkg/model/cache.go

@@ -9,14 +9,32 @@ import (
 
 // CacheEntry represents a single entry in the cache.
 type CacheEntry interface {
+	// Key returns the key associated with the cache entry.
 	Key() string
+
+	// Value returns the value stored in the cache entry.
 	Value() any
+
+	// Age returns the age of the cache entry in seconds.
 	Age() float64
+
+	// Messages retrieves the number of messages processed by the entry.
 	Messages() uint64
+
+	// Bytes returns the size of bytes processed by the entry.
 	Bytes() uint64
+
+	// IsTooOld checks if the entry has exceeded its lifetime.
 	IsTooOld() bool
+
+	// IsValid checks if the entry is still valid.
 	IsValid() bool
+
+	// UpdateMeta updates the metadata of the cache entry
+	// with the number of bytes of plaintext to be encrypted.
 	UpdateMeta(b int)
+
+	// Invalidate marks the cache entry as invalid.
 	Invalidate()
 }
 
@@ -26,17 +44,34 @@ type CacheEntry interface {
 // Custom cache implementations should implement this interface
 // to be used with [CryptoMaterialsManager].
 type Cache interface {
+	// PutEncryptionEntry adds an encryption material to the cache.
+	// It accepts a key, encryption material, n is len of bytes to be encrypted, and lifetime.
+	// The method returns a CacheEntry object containing the added entry.
 	PutEncryptionEntry(key string, em EncryptionMaterial, n int, lifetime time.Duration) CacheEntry
+
+	// PutDecryptionEntry stores a decryption material in the cache with a specified key.
+	// The method returns the added or updated cache entry.
 	PutDecryptionEntry(key string, dm DecryptionMaterial, lifetime time.Duration) CacheEntry
+
+	// GetEncryptionEntry retrieves an encryption entry from the cache using a specified key.
+	// It updates the metadata with the provided number of bytes.
+	// Returns the cache entry and a boolean indicating success.
 	GetEncryptionEntry(key string, n int) (CacheEntry, bool)
+
+	// GetDecryptionEntry retrieves a decryption entry from the cache using a key.
+	// It returns the cache entry and a boolean indicating success.
 	GetDecryptionEntry(key string) (CacheEntry, bool)
+
+	// DeleteEntry removes the cache entry associated with the specified key.
+	// It returns true if the entry was removed successfully.
 	DeleteEntry(key string) bool
+
+	// Len returns the number of entries in the cache.
 	Len() int
 }
 
 // CacheHasher defines an interface to compute hashes for cache keys.
 type CacheHasher interface {
-
 	// Update processes the input byte slice `p` to update the hash state.
 	Update(p []byte)