From e281b2b16d026a5068596ad8c657659fadb32b74 Mon Sep 17 00:00:00 2001
From: "Diogo Franco (Kovensky)" <diogomfranco@gmail.com>
Date: Sun, 14 Jul 2013 12:42:42 -0300
Subject: [PATCH] anidb: Update documentation

---
 anidb.go      | 1 +
 cache.go      | 6 ++++++
 filecache.go  | 6 ++++++
 misc.go       | 1 +
 titlecache.go | 4 ++--
 5 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/anidb.go b/anidb.go
index 812f4c4..1b69e71 100644
--- a/anidb.go
+++ b/anidb.go
@@ -5,6 +5,7 @@ import (
 	"time"
 )
 
+// Main struct for the client, contains all non-shared state.
 type AniDB struct {
 	Timeout time.Duration // Timeout for the various calls (default: 45s)
 
diff --git a/cache.go b/cache.go
index fff97cb..1f1db42 100644
--- a/cache.go
+++ b/cache.go
@@ -52,6 +52,11 @@ func init() {
 
 var cache cacheDir
 
+// Sets the cache directory to the given path.
+//
+// go-anidb needs a valid cache directory to function, so, during module
+// initialization, it uses os.TempDir() to set a default cache dir.
+// go-anidb panics if it's unable to set the default cache dir.
 func SetCacheDir(path string) (err error) {
 	m := cache.RWMutex
 	if m == nil {
@@ -75,6 +80,7 @@ func SetCacheDir(path string) (err error) {
 	return nil
 }
 
+// Returns the current cache dir.
 func GetCacheDir() (path string) {
 	cache.RLock()
 	defer cache.RUnlock()
diff --git a/filecache.go b/filecache.go
index 41b5984..69c8741 100644
--- a/filecache.go
+++ b/filecache.go
@@ -80,6 +80,9 @@ func (f *File) Prefetch(adb *AniDB) <-chan *File {
 	return ch
 }
 
+// Returns the File from the cache if possible.
+//
+// If the File is stale, then retrieves the File through the UDP API.
 func (adb *AniDB) FileByID(fid FID) <-chan *File {
 	keys := []cacheKey{"fid", fid}
 
@@ -124,6 +127,9 @@ func (adb *AniDB) FileByID(fid FID) <-chan *File {
 	return ch
 }
 
+// Returns the File from the cache if possible.
+//
+// If the File is stale, then retrieves the File through the UDP API.
 func (adb *AniDB) FileByEd2kSize(ed2k string, size int64) <-chan *File {
 	keys := []cacheKey{"fid", "by-ed2k", ed2k, size}
 
diff --git a/misc.go b/misc.go
index f738d28..22a010c 100644
--- a/misc.go
+++ b/misc.go
@@ -15,6 +15,7 @@ var (
 	GroupCacheDuration   = 4 * DefaultCacheDuration // They don't change that often.
 	FileCacheDuration    = 8 * DefaultCacheDuration // These change even less often.
 
+	// Used when a request uses a non-existing key (AID, ed2k+size, etc)
 	InvalidKeyCacheDuration = 1 * time.Hour
 
 	// Used when the UDP API Anime query fails, but the HTTP API query succeeds.
diff --git a/titlecache.go b/titlecache.go
index 1100df0..64b1006 100644
--- a/titlecache.go
+++ b/titlecache.go
@@ -9,7 +9,7 @@ import (
 
 var titlesDB = &titles.TitlesDatabase{}
 
-// Reloads titles from the cache.
+// Loads the database from anime-titles.dat.gz in the cache dir.
 func RefreshTitles() error {
 	flock := lockFile(cachePath("anime-titles.dat.gz"))
 	flock.Lock()
@@ -32,7 +32,7 @@ func TitlesUpToDate() (ok bool) {
 
 // Downloads a new anime-titles database if the database is outdated.
 //
-// Caches the contents on memory, which gets saved by DumpCaches.
+// Saves the database as anime-titles.dat.gz in the cache dir.
 func UpdateTitles() error {
 	// too new, no need to update
 	if TitlesUpToDate() {
-- 
2.44.0