add comments in cache package files.

cache/file.go

@@ -24,6 +24,8 @@ func init() {
 	Register("file", NewFileCache())
 }
 
+// FileCacheItem is basic unit of file cache adapter.
+// it contains data and expire time.
 type FileCacheItem struct {
 	Data       interface{}
 	Lastaccess int64
@@ -31,15 +33,13 @@ type FileCacheItem struct {
 }
 
 var (
-	FileCachePath           string = "cache"
-	FileCacheFileSuffix     string = ".bin"
-	FileCacheDirectoryLevel int    = 2
-	/**
-	 * 默认永不过期
-	 */
-	FileCacheEmbedExpiry int64 = 0
+	FileCachePath           string = "cache" // cache directory
+	FileCacheFileSuffix     string = ".bin"  // cache file suffix
+	FileCacheDirectoryLevel int    = 2       // cache file deep level if auto generated cache files.
+	FileCacheEmbedExpiry    int64  = 0       // cache expire time, default is no expire forever.
 )
 
+// FileCache is cache adapter for file storage.
 type FileCache struct {
 	CachePath      string
 	FileSuffix     string
@@ -47,11 +47,14 @@ type FileCache struct {
 	EmbedExpiry    int
 }
 
+// Create new file cache with default directory and suffix.
+// the level and expiry need set in method StartAndGC as config string.
 func NewFileCache() *FileCache {
-	//    return &FileCache{CachePath:FileCachePath, FileSuffix:FileCacheFileSuffix}
 	return &FileCache{}
 }
 
+// Start and begin gc for file cache.
+// the config need to be like {CachePath:"/cache","FileSuffix":".bin","DirectoryLevel":2,"EmbedExpiry":0}
 func (this *FileCache) StartAndGC(config string) error {
 
 	var cfg map[string]string
@@ -78,6 +81,7 @@ func (this *FileCache) StartAndGC(config string) error {
 	return nil
 }
 
+// Init will make new dir for file cache if not exist.
 func (this *FileCache) Init() {
 	app := filepath.Dir(os.Args[0])
 	this.CachePath = filepath.Join(app, this.CachePath)
@@ -93,6 +97,7 @@ func (this *FileCache) Init() {
 	//fmt.Println(this.getCacheFileName("123456"));
 }
 
+// get cached file name. it's md5 encoded.
 func (this *FileCache) getCacheFileName(key string) string {
 	m := md5.New()
 	io.WriteString(m, key)
@@ -119,6 +124,8 @@ func (this *FileCache) getCacheFileName(key string) string {
 	return filepath.Join(cachePath, fmt.Sprintf("%s%s", keyMd5, this.FileSuffix))
 }
 
+// Get value from file cache.
+// if non-exist or expired, return empty string.
 func (this *FileCache) Get(key string) interface{} {
 	filename := this.getCacheFileName(key)
 	filedata, err := File_get_contents(filename)
@@ -134,6 +141,8 @@ func (this *FileCache) Get(key string) interface{} {
 	return to.Data
 }
 
+// Put value into file cache.
+// timeout means how long to keep this file, unit of second.
 func (this *FileCache) Put(key string, val interface{}, timeout int64) error {
 	filename := this.getCacheFileName(key)
 	var item FileCacheItem
@@ -152,6 +161,7 @@ func (this *FileCache) Put(key string, val interface{}, timeout int64) error {
 	return err
 }
 
+// Delete file cache value.
 func (this *FileCache) Delete(key string) error {
 	filename := this.getCacheFileName(key)
 	if ok, _ := exists(filename); ok {
@@ -160,6 +170,8 @@ func (this *FileCache) Delete(key string) error {
 	return nil
 }
 
+// Increase cached int value.
+// this value is saving forever unless Delete.
 func (this *FileCache) Incr(key string) error {
 	data := this.Get(key)
 	var incr int
@@ -173,6 +185,7 @@ func (this *FileCache) Incr(key string) error {
 	return nil
 }
 
+// Decrease cached int value.
 func (this *FileCache) Decr(key string) error {
 	data := this.Get(key)
 	var decr int
@@ -185,18 +198,22 @@ func (this *FileCache) Decr(key string) error {
 	return nil
 }
 
+// Check value is exist.
 func (this *FileCache) IsExist(key string) bool {
 	filename := this.getCacheFileName(key)
 	ret, _ := exists(filename)
 	return ret
 }
 
+// Clean cached files.
+// not implemented.
 func (this *FileCache) ClearAll() error {
 	//this.CachePath .递归删除
 
 	return nil
 }
 
+// check file exist.
 func exists(path string) (bool, error) {
 	_, err := os.Stat(path)
 	if err == nil {
@@ -208,7 +225,9 @@ func exists(path string) (bool, error) {
 	return false, err
 }
 
-func File_get_contents(filename string) ([]byte, error) { //文件不存在时自动创建
+// Get bytes to file.
+// if non-exist, create this file.
+func File_get_contents(filename string) ([]byte, error) {
 	f, err := os.OpenFile(filename, os.O_RDWR|os.O_CREATE, os.ModePerm)
 	if err != nil {
 		return []byte(""), err
@@ -226,6 +245,8 @@ func File_get_contents(filename string) ([]byte, error) { //文件不存在时
 	return []byte(""), err
 }
 
+// Put bytes to file.
+// if non-exist, create this file.
 func File_put_contents(filename string, content []byte) error {
 	fp, err := os.OpenFile(filename, os.O_RDWR|os.O_CREATE, os.ModePerm)
 	if err != nil {
@@ -235,6 +256,8 @@ func File_put_contents(filename string, content []byte) error {
 	_, err = fp.Write(content)
 	return err
 }
+
+// Gob encodes file cache item.
 func Gob_encode(data interface{}) ([]byte, error) {
 	buf := bytes.NewBuffer(nil)
 	enc := gob.NewEncoder(buf)
@@ -245,6 +268,7 @@ func Gob_encode(data interface{}) ([]byte, error) {
 	return buf.Bytes(), err
 }
 
+// Gob decodes file cache item.
 func Gob_decode(data []byte, to interface{}) error {
 	buf := bytes.NewBuffer(data)
 	dec := gob.NewDecoder(buf)