Update documentation

2 files changed, 20 insertions, 13 deletions

diff --git a/cache/cache.go b/cache/cache.go
index a31aeff..a0218b0 100644
--- a/cache/cache.go
+++ b/cache/cache.go
@@ -14,7 +14,7 @@ import (
 	"github.com/mpolden/zdns/dns/dnsutil"
 )
 
-// Backend is the interface for a persistent cache backend.
+// Backend is the interface for a cache backend. All write operations in a Cache are forwarded to a Backend.
 type Backend interface {
 	Set(key uint32, value Value)
 	Evict(key uint32)
@@ -109,7 +109,11 @@ func Unpack(value string) (Value, error) {
 // New creates a new cache of given capacity.
 //
 // If client is non-nil, the cache will prefetch expired entries in an effort to serve results faster.
-// If backend is non-nil, the cache will use it to persist cache entries.
+//
+// If backend is non-nil:
+//
+// - All cache write operations will be forward to the backend.
+// - The backed will be used to pre-populate the cache.
 func New(capacity int, client *dnsutil.Client) *Cache {
 	return NewWithBackend(capacity, client, &defaultBackend{})
 }
diff --git a/sql/cache.go b/sql/cache.go
index 851ea5f..a40f2df 100644
--- a/sql/cache.go
+++ b/sql/cache.go
@@ -19,7 +19,7 @@ type query struct {
 	value cache.Value
 }
 
-// Cache is a persistent cache. Entries are written to a SQL database.
+// Cache is a persistent DNS cache. Values added to the cache are written to a SQL database.
 type Cache struct {
 	wg     sync.WaitGroup
 	queue  chan query
@@ -27,7 +27,7 @@ type Cache struct {
 	logger *log.Logger
 }
 
-// NewCache creates a new cache using client to persist entries.
+// NewCache creates a new cache using client for persistence.
 func NewCache(client *Client) *Cache {
 	c := &Cache{
 		queue:  make(chan query, 1024),
@@ -37,19 +37,22 @@ func NewCache(client *Client) *Cache {
 	return c
 }
 
-// Close consumes any outstanding queued requests and closes the cache.
+// Close consumes any outstanding writes and closes the cache.
 func (c *Cache) Close() error {
 	c.wg.Wait()
 	return nil
 }
 
-// Set associates the value v with key.
-func (c *Cache) Set(key uint32, v cache.Value) { c.enqueue(query{op: setOp, key: key, value: v}) }
+// Set queues a write associating value with key. Set is non-blocking, but read operations wait for any pending writes
+// to complete before reading.
+func (c *Cache) Set(key uint32, value cache.Value) {
+	c.enqueue(query{op: setOp, key: key, value: value})
+}
 
-// Evict removes any value associated with key.
+// Evict queues a removal of key. As Set, Evict is non-blocking.
 func (c *Cache) Evict(key uint32) { c.enqueue(query{op: removeOp, key: key}) }
 
-// Reset removes all entries from the cache.
+// Reset queues removal of all entries. As Set, Reset is non-blocking.
 func (c *Cache) Reset() { c.enqueue(query{op: resetOp}) }
 
 // Read returns all entries in the cache.
@@ -82,18 +85,18 @@ func (c *Cache) readQueue() {
 		case setOp:
 			packed, err := q.value.Pack()
 			if err != nil {
-				c.logger.Fatalf("failed to pack value: %w", err)
+				c.logger.Fatalf("failed to pack value: %s", err)
 			}
 			if err := c.client.writeCacheValue(q.key, packed); err != nil {
-				c.logger.Printf("failed to write key=%d data=%q: %w", q.key, packed, err)
+				c.logger.Printf("failed to write key=%d data=%q: %s", q.key, packed, err)
 			}
 		case removeOp:
 			if err := c.client.removeCacheValue(q.key); err != nil {
-				c.logger.Printf("failed to remove key=%d: %w", q.key, err)
+				c.logger.Printf("failed to remove key=%d: %s", q.key, err)
 			}
 		case resetOp:
 			if err := c.client.truncateCache(); err != nil {
-				c.logger.Printf("failed to truncate cache: %w", err)
+				c.logger.Printf("failed to truncate cache: %s", err)
 			}
 		default:
 			c.logger.Printf("unhandled operation %d", q.op)