document token ownership requirements for Config.Client and ReuseToke…

…nSource

When used with tokens issued by a server supporting refresh token rotation it is unsafe to continuing using the token provided to ReuseTokenSource (including via the Client method of Config) outside of the returned TokenSource and/or Client as it leads to a race condition when the first renewal happens:

* If ReuseTokenSource renews its token first, the original token's RefreshToken is now invalid (revoked) and any use/renewal attempt will fail. 
* If the original token renews its token first, the ReuseTokenSource holds the invliad RefreshToken and will fail on the next usage attempt.

golang#84 has extensive discussion of related risks and complications when trying to cache or store the RefreshToken, but the generic risk of race conditions exists regardless of whether any caching or storage is being attempted and API users must be warned of this possibility.

oauth2.go

@@ -235,7 +235,8 @@ func (c *Config) Exchange(ctx context.Context, code string, opts ...AuthCodeOpti
 }
 
 // Client returns an HTTP client using the provided token.
-// The token will auto-refresh as necessary. The underlying
+// The token will auto-refresh as necessary using a ReuseTokenSource, and
+// therefore should not be used directly after this call. The underlying
 // HTTP transport will be obtained using the provided context.
 // The returned client and its Transport should not be modified.
 func (c *Config) Client(ctx context.Context, t *Token) *http.Client {
@@ -368,6 +369,11 @@ func NewClient(ctx context.Context, src TokenSource) *http.Client {
 // same token as long as it's valid, starting with t.
 // When its cached token is invalid, a new token is obtained from src.
 //
+// When used with tokens issued by a server implementing refresh token
+// rotation the initial token t must be treated as owned by the returned
+// TokenSource and not directly used further to avoid race conditions
+// associated with refresh token invalidation.
+//
 // ReuseTokenSource is typically used to reuse tokens from a cache
 // (such as a file on disk) between runs of a program, rather than
 // obtaining new tokens unnecessarily.