From 9fbe1a4edd22865d9b23523c8d7431b3db9338ba Mon Sep 17 00:00:00 2001
From: Patrick Mylund Nielsen <patrick@patrickmylund.com>
Date: Tue, 3 Jan 2012 12:03:43 +0100
Subject: [PATCH] Library reference in README

---
 README   | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 cache.go |  9 +++++----
 2 files changed, 57 insertions(+), 4 deletions(-)

diff --git a/README b/README
index 5ee7182..5f5d2f1 100644
--- a/README
+++ b/README
@@ -74,3 +74,55 @@ with Get will point you to the same data:
 will print:
     1
     2
+
+Reference:
+
+func New(de, ci time.Duration) *Cache
+Returns a new cache with a given default expiration duration and default cleanup
+interval. If the expiration duration is less than 1, the items in the cache never
+expire and must be deleted manually. If the cleanup interval is less than one,
+expired items are not deleted from the cache before their next lookup or before
+calling DeleteExpired.
+
+func (c *Cache) Set(k string, x interface{}, d time.Duration)
+Adds an item to the cache, replacing any existing item. If the duration is 0, the
+cache's default expiration time is used. If it is -1, the item never expires.
+
+func (c *Cache) Add(k string, x interface{}, d time.Duration) error
+Adds an item to the cache only if an item doesn't already exist for the given key,
+or if the existing item has expired. Returns an error if not.
+
+func (c *Cache) Replace(k string, x interface{}, d time.Duration) error
+Sets a new value for the cache item only if it already exists. Returns an error if
+it does not.
+
+func (c *Cache) Get(k string) (interface{}, bool)
+Gets an item from the cache. Returns the item or nil, and a bool indicating whether
+the given key was found in the cache.
+
+func (c *Cache) Increment(k string, n int64) error
+Increment an item of type int, int8, int16, int32, int64, uintptr, uint, uint8,
+uint32, or uint64, float32 or float64 by n. Returns an error if the item's value
+is not an integer, if it was not found, or if it is not possible to increment it
+by n. Passing a negative number will cause the item to be decremented.
+
+func (c *Cache) IncrementFloat(k string, n float64) error
+Increment an item of type int, int8, int16, int32, int64, uintptr, uint, uint8,
+uint32, uint64, float32 or float64 by n. Returns an error if the item's value is
+not an integer, if it was not found, or if it is not possible to increment it by
+n. Passing a negative number will cause the item to be decremented.
+
+func (c *Cache) Decrement(k string, n int64) error
+Decrement an item of type int, int8, int16, int32, int64, uintptr, uint, uint8,
+uint32, or uint64, float32 or float64 by n. Returns an error if the item's value
+is not an integer, if it was not found, or if it is not possible to decrement it
+by n.
+
+func (c *Cache) Delete(k string)
+Deletes an item from the cache. Does nothing if the item does not exist in the cache.
+
+func (c *Cache) DeleteExpired()
+Deletes all expired items from the cache.
+
+func (c *Cache) Flush()
+Deletes all items from the cache.
diff --git a/cache.go b/cache.go
index f784b66..04978df 100644
--- a/cache.go
+++ b/cache.go
@@ -151,7 +151,8 @@ func (c *cache) Replace(k string, x interface{}, d time.Duration) error {
 	return nil
 }
 
-// Gets an item from the cache.
+// Gets an item from the cache. Returns the item or nil, and a bool indicating whether
+// the given key was found in the cache.
 func (c *cache) Get(k string) (interface{}, bool) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -170,7 +171,7 @@ func (c *cache) Get(k string) (interface{}, bool) {
 // Increment an item of type int, int8, int16, int32, int64, uintptr, uint, uint8,
 // uint32, uint64, float32 or float64 by n. Returns an error if the item's value is
 // not an integer, if it was not found, or if it is not possible to increment it by
-// n.
+// n. Passing a negative number will cause the item to be decremented.
 func (c *cache) IncrementFloat(k string, n float64) error {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -217,7 +218,7 @@ func (c *cache) IncrementFloat(k string, n float64) error {
 // Increment an item of type int, int8, int16, int32, int64, uintptr, uint, uint8,
 // uint32, or uint64, float32 or float64 by n. Returns an error if the item's value
 // is not an integer, if it was not found, or if it is not possible to increment it
-// by n.
+// by n. Passing a negative number will cause the item to be decremented.
 func (c *cache) Increment(k string, n int64) error {
 	return c.IncrementFloat(k, float64(n))
 }
@@ -250,7 +251,7 @@ func (c *cache) DeleteExpired() {
 	}
 }
 
-// Deletes all items in the cache
+// Deletes all items from the cache.
 func (c *cache) Flush() {
 	c.mu.Lock()
 	defer c.mu.Unlock()