Provide missing docs for Cache interface and transport constructors.

cache.go

@@ -12,10 +12,9 @@ import (
 
 // Cache represents a token cacher.
 type Cache interface {
-	// Reads a cached token.
+	// Reads a cached token. It may return nil if none is cached.
-	// It may return a nil value if no token is cached.
 	Read() (token *Token, err error)
-	// Write writes a token to the specified file.
+	// Write writes a token to the cache.
 	Write(token *Token)
 }
 
@@ -32,6 +31,8 @@ type FileCache struct {
 	filename string
 }
 
+// Read reads the token from the cache file. If there exists no cache
+// file, it returns nil for the token.
 func (f *FileCache) Read() (token *Token, err error) {
 	data, err := ioutil.ReadFile(f.filename)
 	if os.IsNotExist(err) {

jwt.go

@@ -76,6 +76,9 @@ func (c *JWTConfig) NewTransportWithUser(user string) Transport {
 	return NewAuthorizedTransport(c, &Token{Subject: user})
 }
 
+// NewTransportWithCache initializes a transport by reading the initial
+// token from the provided cache. If a token refreshing occurs, it
+// writes the newly fetched token back to the cache.
 func (c *JWTConfig) NewTransportWithCache(cache Cache) (Transport, error) {
 	token, err := cache.Read()
 	if err != nil {

oauth2.go

@@ -188,6 +188,9 @@ func (c *Config) NewTransportWithCode(exchangeCode string) (Transport, error) {
 	return NewAuthorizedTransport(c, token), nil
 }
 
+// NewTransportWithCache initializes a transport by reading the initial
+// token from the provided cache. If a token refreshing occurs, it
+// writes the newly fetched token back to the cache.
 func (c *Config) NewTransportWithCache(cache Cache) (Transport, error) {
 	token, err := cache.Read()
 	if err != nil {