From 16ad0434f35e872896bb6424f47f75d744896531 Mon Sep 17 00:00:00 2001
From: "Diogo Franco (Kovensky)" <diogomfranco@gmail.com>
Date: Mon, 15 Jul 2013 01:03:41 -0300
Subject: [PATCH] anidb: Simplify documentation

---
 anidb.go        | 4 ++++
 animecache.go   | 7 ++-----
 episodecache.go | 6 +-----
 filecache.go    | 8 ++------
 groupcache.go   | 6 ++----
 5 files changed, 11 insertions(+), 20 deletions(-)

diff --git a/anidb.go b/anidb.go
index 1b69e71..bfe81d1 100644
--- a/anidb.go
+++ b/anidb.go
@@ -6,6 +6,10 @@ import (
 )
 
 // Main struct for the client, contains all non-shared state.
+//
+// All ObjectByKey methods (AnimeByID, GroupByName, etc) first try to read
+// from the cache. If the sought object isn't cached, or if the cache is
+// stale, then the appropriate API is queried.
 type AniDB struct {
 	Timeout time.Duration // Timeout for the various calls (default: 45s)
 
diff --git a/animecache.go b/animecache.go
index 66c1e6a..2fd1044 100644
--- a/animecache.go
+++ b/animecache.go
@@ -53,11 +53,8 @@ type httpAnimeResponse struct {
 	err   error
 }
 
-// Retrieves an Anime from the cache if possible. If it isn't cached,
-// or if the cache is stale, queries both the UDP and HTTP APIs
-// for data.
-//
-// Note: This can take at least 4 seconds during heavy traffic.
+// Retrieves an Anime by its AID. Uses both HTTP and UDP APIs,
+// but can work without the UDP API.
 func (adb *AniDB) AnimeByID(aid AID) <-chan *Anime {
 	keys := []cacheKey{"aid", aid}
 	ch := make(chan *Anime, 1)
diff --git a/episodecache.go b/episodecache.go
index 008dd98..cfc44d9 100644
--- a/episodecache.go
+++ b/episodecache.go
@@ -39,11 +39,7 @@ func cacheEpisode(ep *Episode) {
 	cache.Set(ep, "eid", ep.EID)
 }
 
-// Retrieves the Episode from the cache if possible.
-//
-// If the result is stale, then queries the UDP API to
-// know which AID owns this EID, then gets the episode
-// from the Anime.
+// Retrieves an Episode by its EID.
 func (adb *AniDB) EpisodeByID(eid EID) <-chan *Episode {
 	keys := []cacheKey{"eid", eid}
 	ch := make(chan *Episode, 1)
diff --git a/filecache.go b/filecache.go
index fbf7066..10ba2ab 100644
--- a/filecache.go
+++ b/filecache.go
@@ -80,9 +80,7 @@ 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.
+// Retrieves a File by its FID.
 func (adb *AniDB) FileByID(fid FID) <-chan *File {
 	keys := []cacheKey{"fid", fid}
 
@@ -127,9 +125,7 @@ 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.
+// Retrieves a File by its Ed2kHash + Filesize combination.
 func (adb *AniDB) FileByEd2kSize(ed2k string, size int64) <-chan *File {
 	keys := []cacheKey{"fid", "by-ed2k", ed2k, size}
 
diff --git a/groupcache.go b/groupcache.go
index dbf3037..6cee348 100644
--- a/groupcache.go
+++ b/groupcache.go
@@ -56,10 +56,7 @@ func (c *gidCache) IsStale() bool {
 	return true
 }
 
-// Returns a Group from the cache if possible.
-//
-// If the Group is stale, then retrieves the Group
-// through the UDP API.
+// Retrieves a Group by its GID.
 func (adb *AniDB) GroupByID(gid GID) <-chan *Group {
 	keys := []cacheKey{"gid", gid}
 	ch := make(chan *Group, 1)
@@ -101,6 +98,7 @@ func (adb *AniDB) GroupByID(gid GID) <-chan *Group {
 	return ch
 }
 
+// Retrieves a Group by its name. Either full or short names are matched.
 func (adb *AniDB) GroupByName(gname string) <-chan *Group {
 	keys := []cacheKey{"gid", "by-name", gname}
 	altKeys := []cacheKey{"gid", "by-shortname", gname}
-- 
2.44.0