From 44563584705e4772305765ecb64e09d890546f32 Mon Sep 17 00:00:00 2001
From: Karl Seguin <karl@openmymind.io>
Date: Sat, 1 Mar 2014 00:44:39 +0800
Subject: [PATCH] config documentation

---
 configuration.go | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/configuration.go b/configuration.go
index f38e855..5da8377 100644
--- a/configuration.go
+++ b/configuration.go
@@ -22,36 +22,66 @@ func Configure() *Configuration {
 	}
 }
 
+// The size, in bytes, of the data to cache
+// [500MB]
 func (c *Configuration) Size(bytes uint64) *Configuration {
 	c.size = bytes
 	return c
 }
 
+// Keys are hashed into % bucket count to provide greater concurrency (every set
+// requires a write lock on the bucket)
+// [64]
 func (c *Configuration) Buckets(count int) *Configuration {
 	c.buckets = count
 	return c
 }
 
+// The number of items to prune when memory is low
+// [500]
 func (c *Configuration) ItemsToPrune(count int) *Configuration {
 	c.itemsToPrune = count
 	return c
 }
 
+// The size of the queue for items which should be promoted. If the queue fills
+// up, promotions are skipped
+// [1024]
 func (c *Configuration) PromoteBuffer(size int) *Configuration {
 	c.promoteBuffer = size
 	return c
 }
 
+// The size of the queue for items which should be deleted. If the queue fills
+// up, calls to Delete() will block
 func (c *Configuration) DeleteBuffer(size int) *Configuration {
 	c.deleteBuffer = size
 	return c
 }
 
+// Give a large cache with a high read / write ratio, it's usually unecessary
+// to promote an item on every Get. GetsPerPromote specifies the number of Gets
+// a key must have before being promoted
+// [10]
 func (c *Configuration) GetsPerPromote(count int) *Configuration {
 	c.getsPerPromote = int32(count)
 	return c
 }
 
+// Typically, a cache is agnostic about how cached values are use. This is fine
+// for a typical cache usage, where you fetch an item from the cache, do something
+// (write it out to) and nothing else.
+
+// However, if callers are going to keep a reference to a cached item for a long
+// time, things get messy. Specifically, the cache can evict the item, while
+// references still exist. Technically, this isn't an issue. However, if you reload
+// the item back into the cache, you end up with 2 objects representing the same
+// data. This is a waste of space and could lead to weird behavior (the type an
+// identity map is meant to solve).
+
+// By turning tracking on and using the cache's TrackingGet, the cache
+// won't evict items which you haven't called Release() on. It's a simple reference
+// counter.
 func (c *Configuration) Track() *Configuration {
 	c.tracking = true
 	return c