From f42d05182288abf10faef86d16c0d07b8d40ea2d Mon Sep 17 00:00:00 2001
From: Adam Shannon <adamkshannon@gmail.com>
Date: Mon, 10 Sep 2018 15:10:05 -0700
Subject: [PATCH] doc: clarify context key usage to override *http.Client

Fixes golang/oauth2#321

Change-Id: I43724b107efafe189a3a76a81f6089dcc75cb167
Reviewed-on: https://go-review.googlesource.com/c/134436
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
---
 clientcredentials/clientcredentials.go | 13 ++++++++-----
 oauth2.go                              |  6 ++----
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/clientcredentials/clientcredentials.go b/clientcredentials/clientcredentials.go
index ba57e4c..3c816bb 100644
--- a/clientcredentials/clientcredentials.go
+++ b/clientcredentials/clientcredentials.go
@@ -45,16 +45,19 @@ type Config struct {
 }
 
 // Token uses client credentials to retrieve a token.
-// The HTTP client to use is derived from the context.
-// If nil, http.DefaultClient is used.
+//
+// The provided context optionally controls which HTTP client is used. See the oauth2.HTTPClient variable.
 func (c *Config) Token(ctx context.Context) (*oauth2.Token, error) {
 	return c.TokenSource(ctx).Token()
 }
 
 // Client returns an HTTP client using the provided token.
-// The token will auto-refresh as necessary. The underlying
-// HTTP transport will be obtained using the provided context.
-// The returned client and its Transport should not be modified.
+// The token will auto-refresh as necessary.
+//
+// The provided context optionally controls which HTTP client
+// is returned. See the oauth2.HTTPClient variable.
+//
+// The returned Client and its Transport should not be modified.
 func (c *Config) Client(ctx context.Context) *http.Client {
 	return oauth2.NewClient(ctx, c.TokenSource(ctx))
 }
diff --git a/oauth2.go b/oauth2.go
index 0a3c1e1..1e8e1b7 100644
--- a/oauth2.go
+++ b/oauth2.go
@@ -164,8 +164,7 @@ func (c *Config) AuthCodeURL(state string, opts ...AuthCodeOption) string {
 // and when other authorization grant types are not available."
 // See https://tools.ietf.org/html/rfc6749#section-4.3 for more info.
 //
-// The HTTP client to use is derived from the context.
-// If nil, http.DefaultClient is used.
+// The provided context optionally controls which HTTP client is used. See the HTTPClient variable.
 func (c *Config) PasswordCredentialsToken(ctx context.Context, username, password string) (*Token, error) {
 	v := url.Values{
 		"grant_type": {"password"},
@@ -183,8 +182,7 @@ func (c *Config) PasswordCredentialsToken(ctx context.Context, username, passwor
 // It is used after a resource provider redirects the user back
 // to the Redirect URI (the URL obtained from AuthCodeURL).
 //
-// The HTTP client to use is derived from the context.
-// If a client is not provided via the context, http.DefaultClient is used.
+// The provided context optionally controls which HTTP client is used. See the HTTPClient variable.
 //
 // The code will be in the *http.Request.FormValue("code"). Before
 // calling Exchange, be sure to validate FormValue("state").