Address review comments

- Move AppEngineTokenSource documentation to one location
- Add file comments
- Log the deprecation message exactly once in the second generation and
  flex AppEngineTokenSource.

google/appengine.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"golang.org/x/net/context"
+	"golang.org/x/oauth2"
 )
 
 // Set at init time by appengine_gen1.go. If nil, we're not on App Engine standard first generation (<= Go 1.9) or App Engine flexible.
@@ -15,3 +16,23 @@ var appengineTokenFunc func(c context.Context, scopes ...string) (token string,
 
 // Set at init time by appengine_gen1.go. If nil, we're not on App Engine standard first generation (<= Go 1.9) or App Engine flexible.
 var appengineAppIDFunc func(c context.Context) string
+
+// AppEngineTokenSource returns a token source that fetches tokens from either
+// the current application's service account or from the metadata server,
+// depending on the App Engine environment. See below for environment-specific
+// details. If you are implementing a 3-legged OAuth 2.0 flow on App Engine that
+// involves user accounts, see oauth2.Config instead.
+//
+// First generation App Engine runtimes (<= Go 1.9):
+// AppEngineTokenSource returns a token source that fetches tokens issued to the
+// current App Engine application's service account. The provided context must have
+// come from appengine.NewContext.
+//
+// Second generation App Engine runtimes (>= Go 1.11) and App Engine flexible:
+// AppEngineTokenSource is DEPRECATED on second generation runtimes and on the
+// flexible environment. It delegates to ComputeTokenSource, and the provided
+// context and scopes are not used. Please use DefaultTokenSource (or ComputeTokenSource,
+// which DefaultTokenSource will use in this case) instead.
+func AppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource {
+	return getAppEngineTokenSource(ctx, scope...)
+}

google/appengine_gen1.go

@@ -4,6 +4,8 @@
 
 // +build appengine
 
+// This file applies to App Engine first generation runtimes (<= Go 1.9).
+
 package google
 
 import (
@@ -21,23 +23,8 @@ func init() {
 	appengineAppIDFunc = appengine.AppID
 }
 
-// AppEngineTokenSource returns a token source that fetches tokens from either
-// the current application's service account or from the metadata server,
-// depending on the App Engine environment. See below for environment-specific
-// details. If you are implementing a 3-legged OAuth 2.0 flow on App Engine that
-// involves user accounts, see oauth2.Config instead.
-//
-// First generation App Engine runtimes (<= Go 1.9):
-// AppEngineTokenSource returns a token source that fetches tokens issued to the
-// current App Engine application's service account. The provided context must have
-// come from appengine.NewContext.
-//
-// Second generation App Engine runtimes (>= Go 1.11) and App Engine flexible:
-// AppEngineTokenSource is DEPRECATED on second generation runtimes and on the
-// flexible environment. It delegates to ComputeTokenSource, and the provided
-// context and scopes are not used. Please use DefaultTokenSource (or ComputeTokenSource,
-// which DefaultTokenSource will use in this case) instead.
-func AppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource {
+// See comment on AppEngineTokenSource in appengine.go.
+func getAppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource {
 	scopes := append([]string{}, scope...)
 	sort.Strings(scopes)
 	return &appEngineTokenSource{

google/appengine_gen2_flex.go

@@ -4,32 +4,28 @@
 
 // +build !appengine
 
+// This file applies to App Engine second generation runtimes (>= Go 1.11) and App Engine flexible.
+
 package google
 
 import (
 	"log"
+	"sync"
 
 	"golang.org/x/net/context"
 	"golang.org/x/oauth2"
 )
 
-// AppEngineTokenSource returns a token source that fetches tokens from either
-// the current application's service account or from the metadata server,
-// depending on the App Engine environment. See below for environment-specific
-// details. If you are implementing a 3-legged OAuth 2.0 flow on App Engine that
-// involves user accounts, see oauth2.Config instead.
-//
-// First generation App Engine runtimes (<= Go 1.9):
-// AppEngineTokenSource returns a token source that fetches tokens issued to the
-// current App Engine application's service account. The provided context must have
-// come from appengine.NewContext.
-//
-// Second generation App Engine runtimes (>= Go 1.11) and App Engine flexible:
-// AppEngineTokenSource is DEPRECATED on second generation runtimes and on the
-// flexible environment. It delegates to ComputeTokenSource, and the provided
-// context and scopes are not used. Please use DefaultTokenSource (or ComputeTokenSource,
-// which DefaultTokenSource will use in this case) instead.
-func AppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource {
-	log.Print("google: AppEngineTokenSource is deprecated on App Engine standard second generation runtimes (>= Go 1.11) and App Engine flexible. Please use DefaultTokenSource or ComputeTokenSource.")
+var (
+	once sync.Once
+
+	logFunc = func() {
+		log.Print("google: AppEngineTokenSource is deprecated on App Engine standard second generation runtimes (>= Go 1.11) and App Engine flexible. Please use DefaultTokenSource or ComputeTokenSource.")
+	}
+)
+
+// See comment on AppEngineTokenSource in appengine.go.
+func getAppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource {
+	once.Do(logFunc)
 	return ComputeTokenSource("")
 }