docs(option): update WithDefaultEndpointTemplate docs (#2356)

quartzmo · web-flow · commit 74a1558e1a34 · 2024-01-17T14:25:45.000-05:00
diff --git a/option/internaloption/internaloption.go b/option/internaloption/internaloption.go
@@ -38,7 +38,10 @@ func (o defaultEndpointTemplateOption) Apply(settings *internal.DialSettings) {
 
 // WithDefaultEndpointTemplate provides a template for creating the endpoint
 // using a universe domain. See also WithDefaultUniverseDomain and
-// option.WithUniverseDomain.
+// option.WithUniverseDomain. The placeholder UNIVERSE_DOMAIN should be used
+// instead of a concrete universe domain such as "googleapis.com".
+//
+// Example: WithDefaultEndpointTemplate("https://logging.UNIVERSE_DOMAIN/")
 //
 // It should only be used internally by generated clients.
 func WithDefaultEndpointTemplate(url string) option.ClientOption {
@@ -163,6 +166,11 @@ func (w withDefaultUniverseDomain) Apply(o *internal.DialSettings) {
 
 // EnableJwtWithScope returns a ClientOption that specifies if scope can be used
 // with self-signed JWT.
+//
+// EnableJwtWithScope is ignored when option.WithUniverseDomain is set
+// to a value other than the Google Default Universe (GDU) of "googleapis.com".
+// For non-GDU domains, token exchange is impossible and services must
+// support self-signed JWTs with scopes.
 func EnableJwtWithScope() option.ClientOption {
 	return enableJwtWithScope(true)
 }
diff --git a/option/internaloption/internaloption_test.go b/option/internaloption/internaloption_test.go
@@ -35,7 +35,7 @@ func TestWithCredentials(t *testing.T) {
 func TestDefaultApply(t *testing.T) {
 	opts := []option.ClientOption{
 		WithDefaultEndpoint("https://example.com:443"),
-		WithDefaultEndpointTemplate("https://foo.%s/"),
+		WithDefaultEndpointTemplate("https://foo.UNIVERSE_DOMAIN/"),
 		WithDefaultMTLSEndpoint("http://mtls.example.com:445"),
 		WithDefaultScopes("a"),
 		WithDefaultUniverseDomain("foo.com"),
@@ -48,7 +48,7 @@ func TestDefaultApply(t *testing.T) {
 	want := internal.DialSettings{
 		DefaultScopes:           []string{"a"},
 		DefaultEndpoint:         "https://example.com:443",
-		DefaultEndpointTemplate: "https://foo.%s/",
+		DefaultEndpointTemplate: "https://foo.UNIVERSE_DOMAIN/",
 		DefaultUniverseDomain:   "foo.com",
 		DefaultAudience:         "audience",
 		DefaultMTLSEndpoint:     "http://mtls.example.com:445",
