From 24a1812d88411ff9b5854758bad3c390217eeb77 Mon Sep 17 00:00:00 2001
From: CodeLingo Bot <bot@codelingo.io>
Date: Sun, 17 Feb 2019 20:41:27 +0000
Subject: [PATCH] Fix function comments based on best practices from Effective
 Go

Signed-off-by: CodeLingo Bot <bot@codelingo.io>
---
 cache.go   | 86 +++++++++++++++++++++++++++---------------------------
 sharded.go |  2 +-
 2 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/cache.go b/cache.go
index db88d2f..46409a0 100644
--- a/cache.go
+++ b/cache.go
@@ -15,7 +15,7 @@ type Item struct {
 	Expiration int64
 }
 
-// Returns true if the item has expired.
+// Expired returns true if the item has expired.
 func (item Item) Expired() bool {
 	if item.Expiration == 0 {
 		return false
@@ -45,7 +45,7 @@ type cache struct {
 	janitor           *janitor
 }
 
-// Add an item to the cache, replacing any existing item. If the duration is 0
+// Set adds an item to the cache, replacing any existing item. If the duration is 0
 // (DefaultExpiration), the cache's default expiration time is used. If it is -1
 // (NoExpiration), the item never expires.
 func (c *cache) Set(k string, x interface{}, d time.Duration) {
@@ -81,7 +81,7 @@ func (c *cache) set(k string, x interface{}, d time.Duration) {
 	}
 }
 
-// Add an item to the cache, replacing any existing item, using the default
+// SetDefault adds an item to the cache, replacing any existing item, using the default
 // expiration.
 func (c *cache) SetDefault(k string, x interface{}) {
 	c.Set(k, x, DefaultExpiration)
@@ -101,7 +101,7 @@ func (c *cache) Add(k string, x interface{}, d time.Duration) error {
 	return nil
 }
 
-// Set a new value for the cache key only if it already exists, and the existing
+// Replace: Set a new value for the cache key only if it already exists, and the existing
 // item hasn't expired. Returns an error otherwise.
 func (c *cache) Replace(k string, x interface{}, d time.Duration) error {
 	c.mu.Lock()
@@ -227,7 +227,7 @@ func (c *cache) Increment(k string, n int64) error {
 	return nil
 }
 
-// Increment an item of type float32 or float64 by n. Returns an error if the
+// IncrementFloat: Increment an item of type float32 or float64 by n. Returns an error if the
 // item's value is not floating point, if it was not found, or if it is not
 // possible to increment it by n. Pass a negative number to decrement the
 // value. To retrieve the incremented value, use one of the specialized methods,
@@ -253,7 +253,7 @@ func (c *cache) IncrementFloat(k string, n float64) error {
 	return nil
 }
 
-// Increment an item of type int by n. Returns an error if the item's value is
+// IncrementInt: Increment an item of type int by n. Returns an error if the item's value is
 // not an int, or if it was not found. If there is no error, the incremented
 // value is returned.
 func (c *cache) IncrementInt(k string, n int) (int, error) {
@@ -275,7 +275,7 @@ func (c *cache) IncrementInt(k string, n int) (int, error) {
 	return nv, nil
 }
 
-// Increment an item of type int8 by n. Returns an error if the item's value is
+// IncrementInt8: Increment an item of type int8 by n. Returns an error if the item's value is
 // not an int8, or if it was not found. If there is no error, the incremented
 // value is returned.
 func (c *cache) IncrementInt8(k string, n int8) (int8, error) {
@@ -297,7 +297,7 @@ func (c *cache) IncrementInt8(k string, n int8) (int8, error) {
 	return nv, nil
 }
 
-// Increment an item of type int16 by n. Returns an error if the item's value is
+// IncrementInt16: Increment an item of type int16 by n. Returns an error if the item's value is
 // not an int16, or if it was not found. If there is no error, the incremented
 // value is returned.
 func (c *cache) IncrementInt16(k string, n int16) (int16, error) {
@@ -319,7 +319,7 @@ func (c *cache) IncrementInt16(k string, n int16) (int16, error) {
 	return nv, nil
 }
 
-// Increment an item of type int32 by n. Returns an error if the item's value is
+// IncrementInt32: Increment an item of type int32 by n. Returns an error if the item's value is
 // not an int32, or if it was not found. If there is no error, the incremented
 // value is returned.
 func (c *cache) IncrementInt32(k string, n int32) (int32, error) {
@@ -341,7 +341,7 @@ func (c *cache) IncrementInt32(k string, n int32) (int32, error) {
 	return nv, nil
 }
 
-// Increment an item of type int64 by n. Returns an error if the item's value is
+// IncrementInt64: Increment an item of type int64 by n. Returns an error if the item's value is
 // not an int64, or if it was not found. If there is no error, the incremented
 // value is returned.
 func (c *cache) IncrementInt64(k string, n int64) (int64, error) {
@@ -363,7 +363,7 @@ func (c *cache) IncrementInt64(k string, n int64) (int64, error) {
 	return nv, nil
 }
 
-// Increment an item of type uint by n. Returns an error if the item's value is
+// IncrementUint: Increment an item of type uint by n. Returns an error if the item's value is
 // not an uint, or if it was not found. If there is no error, the incremented
 // value is returned.
 func (c *cache) IncrementUint(k string, n uint) (uint, error) {
@@ -385,7 +385,7 @@ func (c *cache) IncrementUint(k string, n uint) (uint, error) {
 	return nv, nil
 }
 
-// Increment an item of type uintptr by n. Returns an error if the item's value
+// IncrementUintptr: Increment an item of type uintptr by n. Returns an error if the item's value
 // is not an uintptr, or if it was not found. If there is no error, the
 // incremented value is returned.
 func (c *cache) IncrementUintptr(k string, n uintptr) (uintptr, error) {
@@ -407,7 +407,7 @@ func (c *cache) IncrementUintptr(k string, n uintptr) (uintptr, error) {
 	return nv, nil
 }
 
-// Increment an item of type uint8 by n. Returns an error if the item's value
+// IncrementUint8: Increment an item of type uint8 by n. Returns an error if the item's value
 // is not an uint8, or if it was not found. If there is no error, the
 // incremented value is returned.
 func (c *cache) IncrementUint8(k string, n uint8) (uint8, error) {
@@ -429,7 +429,7 @@ func (c *cache) IncrementUint8(k string, n uint8) (uint8, error) {
 	return nv, nil
 }
 
-// Increment an item of type uint16 by n. Returns an error if the item's value
+// IncrementUint16: Increment an item of type uint16 by n. Returns an error if the item's value
 // is not an uint16, or if it was not found. If there is no error, the
 // incremented value is returned.
 func (c *cache) IncrementUint16(k string, n uint16) (uint16, error) {
@@ -451,7 +451,7 @@ func (c *cache) IncrementUint16(k string, n uint16) (uint16, error) {
 	return nv, nil
 }
 
-// Increment an item of type uint32 by n. Returns an error if the item's value
+// IncrementUint32: Increment an item of type uint32 by n. Returns an error if the item's value
 // is not an uint32, or if it was not found. If there is no error, the
 // incremented value is returned.
 func (c *cache) IncrementUint32(k string, n uint32) (uint32, error) {
@@ -473,7 +473,7 @@ func (c *cache) IncrementUint32(k string, n uint32) (uint32, error) {
 	return nv, nil
 }
 
-// Increment an item of type uint64 by n. Returns an error if the item's value
+// IncrementUint64: Increment an item of type uint64 by n. Returns an error if the item's value
 // is not an uint64, or if it was not found. If there is no error, the
 // incremented value is returned.
 func (c *cache) IncrementUint64(k string, n uint64) (uint64, error) {
@@ -495,7 +495,7 @@ func (c *cache) IncrementUint64(k string, n uint64) (uint64, error) {
 	return nv, nil
 }
 
-// Increment an item of type float32 by n. Returns an error if the item's value
+// IncrementFloat32: Increment an item of type float32 by n. Returns an error if the item's value
 // is not an float32, or if it was not found. If there is no error, the
 // incremented value is returned.
 func (c *cache) IncrementFloat32(k string, n float32) (float32, error) {
@@ -517,7 +517,7 @@ func (c *cache) IncrementFloat32(k string, n float32) (float32, error) {
 	return nv, nil
 }
 
-// Increment an item of type float64 by n. Returns an error if the item's value
+// IncrementFloat64: Increment an item of type float64 by n. Returns an error if the item's value
 // is not an float64, or if it was not found. If there is no error, the
 // incremented value is returned.
 func (c *cache) IncrementFloat64(k string, n float64) (float64, error) {
@@ -589,7 +589,7 @@ func (c *cache) Decrement(k string, n int64) error {
 	return nil
 }
 
-// Decrement an item of type float32 or float64 by n. Returns an error if the
+// DecrementFloat: Decrement an item of type float32 or float64 by n. Returns an error if the
 // item's value is not floating point, if it was not found, or if it is not
 // possible to decrement it by n. Pass a negative number to decrement the
 // value. To retrieve the decremented value, use one of the specialized methods,
@@ -615,7 +615,7 @@ func (c *cache) DecrementFloat(k string, n float64) error {
 	return nil
 }
 
-// Decrement an item of type int by n. Returns an error if the item's value is
+// DecrementInt: Decrement an item of type int by n. Returns an error if the item's value is
 // not an int, or if it was not found. If there is no error, the decremented
 // value is returned.
 func (c *cache) DecrementInt(k string, n int) (int, error) {
@@ -637,7 +637,7 @@ func (c *cache) DecrementInt(k string, n int) (int, error) {
 	return nv, nil
 }
 
-// Decrement an item of type int8 by n. Returns an error if the item's value is
+// DecrementInt8: Decrement an item of type int8 by n. Returns an error if the item's value is
 // not an int8, or if it was not found. If there is no error, the decremented
 // value is returned.
 func (c *cache) DecrementInt8(k string, n int8) (int8, error) {
@@ -659,7 +659,7 @@ func (c *cache) DecrementInt8(k string, n int8) (int8, error) {
 	return nv, nil
 }
 
-// Decrement an item of type int16 by n. Returns an error if the item's value is
+// DecrementInt16: Decrement an item of type int16 by n. Returns an error if the item's value is
 // not an int16, or if it was not found. If there is no error, the decremented
 // value is returned.
 func (c *cache) DecrementInt16(k string, n int16) (int16, error) {
@@ -681,7 +681,7 @@ func (c *cache) DecrementInt16(k string, n int16) (int16, error) {
 	return nv, nil
 }
 
-// Decrement an item of type int32 by n. Returns an error if the item's value is
+// DecrementInt32: Decrement an item of type int32 by n. Returns an error if the item's value is
 // not an int32, or if it was not found. If there is no error, the decremented
 // value is returned.
 func (c *cache) DecrementInt32(k string, n int32) (int32, error) {
@@ -703,7 +703,7 @@ func (c *cache) DecrementInt32(k string, n int32) (int32, error) {
 	return nv, nil
 }
 
-// Decrement an item of type int64 by n. Returns an error if the item's value is
+// DecrementInt64: Decrement an item of type int64 by n. Returns an error if the item's value is
 // not an int64, or if it was not found. If there is no error, the decremented
 // value is returned.
 func (c *cache) DecrementInt64(k string, n int64) (int64, error) {
@@ -725,7 +725,7 @@ func (c *cache) DecrementInt64(k string, n int64) (int64, error) {
 	return nv, nil
 }
 
-// Decrement an item of type uint by n. Returns an error if the item's value is
+// DecrementUint: Decrement an item of type uint by n. Returns an error if the item's value is
 // not an uint, or if it was not found. If there is no error, the decremented
 // value is returned.
 func (c *cache) DecrementUint(k string, n uint) (uint, error) {
@@ -747,7 +747,7 @@ func (c *cache) DecrementUint(k string, n uint) (uint, error) {
 	return nv, nil
 }
 
-// Decrement an item of type uintptr by n. Returns an error if the item's value
+// DecrementUintptr: Decrement an item of type uintptr by n. Returns an error if the item's value
 // is not an uintptr, or if it was not found. If there is no error, the
 // decremented value is returned.
 func (c *cache) DecrementUintptr(k string, n uintptr) (uintptr, error) {
@@ -769,7 +769,7 @@ func (c *cache) DecrementUintptr(k string, n uintptr) (uintptr, error) {
 	return nv, nil
 }
 
-// Decrement an item of type uint8 by n. Returns an error if the item's value is
+// DecrementUint8: Decrement an item of type uint8 by n. Returns an error if the item's value is
 // not an uint8, or if it was not found. If there is no error, the decremented
 // value is returned.
 func (c *cache) DecrementUint8(k string, n uint8) (uint8, error) {
@@ -791,7 +791,7 @@ func (c *cache) DecrementUint8(k string, n uint8) (uint8, error) {
 	return nv, nil
 }
 
-// Decrement an item of type uint16 by n. Returns an error if the item's value
+// DecrementUint16: Decrement an item of type uint16 by n. Returns an error if the item's value
 // is not an uint16, or if it was not found. If there is no error, the
 // decremented value is returned.
 func (c *cache) DecrementUint16(k string, n uint16) (uint16, error) {
@@ -813,7 +813,7 @@ func (c *cache) DecrementUint16(k string, n uint16) (uint16, error) {
 	return nv, nil
 }
 
-// Decrement an item of type uint32 by n. Returns an error if the item's value
+// DecrementUint32: Decrement an item of type uint32 by n. Returns an error if the item's value
 // is not an uint32, or if it was not found. If there is no error, the
 // decremented value is returned.
 func (c *cache) DecrementUint32(k string, n uint32) (uint32, error) {
@@ -835,7 +835,7 @@ func (c *cache) DecrementUint32(k string, n uint32) (uint32, error) {
 	return nv, nil
 }
 
-// Decrement an item of type uint64 by n. Returns an error if the item's value
+// DecrementUint64: Decrement an item of type uint64 by n. Returns an error if the item's value
 // is not an uint64, or if it was not found. If there is no error, the
 // decremented value is returned.
 func (c *cache) DecrementUint64(k string, n uint64) (uint64, error) {
@@ -857,7 +857,7 @@ func (c *cache) DecrementUint64(k string, n uint64) (uint64, error) {
 	return nv, nil
 }
 
-// Decrement an item of type float32 by n. Returns an error if the item's value
+// DecrementFloat32: Decrement an item of type float32 by n. Returns an error if the item's value
 // is not an float32, or if it was not found. If there is no error, the
 // decremented value is returned.
 func (c *cache) DecrementFloat32(k string, n float32) (float32, error) {
@@ -879,7 +879,7 @@ func (c *cache) DecrementFloat32(k string, n float32) (float32, error) {
 	return nv, nil
 }
 
-// Decrement an item of type float64 by n. Returns an error if the item's value
+// DecrementFloat64: Decrement an item of type float64 by n. Returns an error if the item's value
 // is not an float64, or if it was not found. If there is no error, the
 // decremented value is returned.
 func (c *cache) DecrementFloat64(k string, n float64) (float64, error) {
@@ -927,7 +927,7 @@ type keyAndValue struct {
 	value interface{}
 }
 
-// Delete all expired items from the cache.
+// DeleteExpired: Delete all expired items from the cache.
 func (c *cache) DeleteExpired() {
 	var evictedItems []keyAndValue
 	now := time.Now().UnixNano()
@@ -947,7 +947,7 @@ func (c *cache) DeleteExpired() {
 	}
 }
 
-// Sets an (optional) function that is called with the key and value when an
+// OnEvicted: Sets an (optional) function that is called with the key and value when an
 // item is evicted from the cache. (Including when it is deleted manually, but
 // not when it is overwritten.) Set to nil to disable.
 func (c *cache) OnEvicted(f func(string, interface{})) {
@@ -956,7 +956,7 @@ func (c *cache) OnEvicted(f func(string, interface{})) {
 	c.mu.Unlock()
 }
 
-// Write the cache's items (using Gob) to an io.Writer.
+// Save writes the cache's items (using Gob) to an io.Writer.
 //
 // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
 // documentation for NewFrom().)
@@ -976,7 +976,7 @@ func (c *cache) Save(w io.Writer) (err error) {
 	return
 }
 
-// Save the cache's items to the given filename, creating the file if it
+// SaveFile: Save the cache's items to the given filename, creating the file if it
 // doesn't exist, and overwriting it if it does.
 //
 // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
@@ -994,7 +994,7 @@ func (c *cache) SaveFile(fname string) error {
 	return fp.Close()
 }
 
-// Add (Gob-serialized) cache items from an io.Reader, excluding any items with
+// Load adds (Gob-serialized) cache items from an io.Reader, excluding any items with
 // keys that already exist (and haven't expired) in the current cache.
 //
 // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
@@ -1016,7 +1016,7 @@ func (c *cache) Load(r io.Reader) error {
 	return err
 }
 
-// Load and add cache items from the given filename, excluding any items with
+// LoadFile: Load and add cache items from the given filename, excluding any items with
 // keys that already exist in the current cache.
 //
 // NOTE: This method is deprecated in favor of c.Items() and NewFrom() (see the
@@ -1034,7 +1034,7 @@ func (c *cache) LoadFile(fname string) error {
 	return fp.Close()
 }
 
-// Copies all unexpired items in the cache into a new map and returns it.
+// Items: Copies all unexpired items in the cache into a new map and returns it.
 func (c *cache) Items() map[string]Item {
 	c.mu.RLock()
 	defer c.mu.RUnlock()
@@ -1052,7 +1052,7 @@ func (c *cache) Items() map[string]Item {
 	return m
 }
 
-// Returns the number of items in the cache. This may include items that have
+// ItemCount returns the number of items in the cache. This may include items that have
 // expired, but have not yet been cleaned up.
 func (c *cache) ItemCount() int {
 	c.mu.RLock()
@@ -1061,7 +1061,7 @@ func (c *cache) ItemCount() int {
 	return n
 }
 
-// Delete all items from the cache.
+// Flush: Delete all items from the cache.
 func (c *cache) Flush() {
 	c.mu.Lock()
 	c.items = map[string]Item{}
@@ -1125,7 +1125,7 @@ func newCacheWithJanitor(de time.Duration, ci time.Duration, m map[string]Item)
 	return C
 }
 
-// Return a new cache with a given default expiration duration and cleanup
+// New returns a new cache with a given default expiration duration and cleanup
 // interval. If the expiration duration is less than one (or NoExpiration),
 // the items in the cache never expire (by default), and must be deleted
 // manually. If the cleanup interval is less than one, expired items are not
@@ -1135,7 +1135,7 @@ func New(defaultExpiration, cleanupInterval time.Duration) *Cache {
 	return newCacheWithJanitor(defaultExpiration, cleanupInterval, items)
 }
 
-// Return a new cache with a given default expiration duration and cleanup
+// NewFrom returns a new cache with a given default expiration duration and cleanup
 // interval. If the expiration duration is less than one (or NoExpiration),
 // the items in the cache never expire (by default), and must be deleted
 // manually. If the cleanup interval is less than one, expired items are not
diff --git a/sharded.go b/sharded.go
index bcc0538..2fc8d69 100644
--- a/sharded.go
+++ b/sharded.go
@@ -104,7 +104,7 @@ func (sc *shardedCache) DeleteExpired() {
 	}
 }
 
-// Returns the items in the cache. This may include items that have expired,
+// Items returns the items in the cache. This may include items that have expired,
 // but have not yet been cleaned up. If this is significant, the Expiration
 // fields of the items should be checked. Note that explicit synchronization
 // is needed to use a cache and its corresponding Items() return values at