chore: Review feedback from Nick Young

Clarify that empty string and unset are equivalent

Co-authored-by: Nick Young <[email protected]>

Signed-off-by: Flynn <[email protected]>

Author: kflynn

apis/v1/gateway_types.go

@@ -295,8 +295,9 @@ type GatewaySpec struct {
 	// <gateway:experimental>
 	TLS *GatewayTLSConfig `json:"tls,omitempty"`
 
-	// DefaultScope defines the default scope for this Gateway. If unset (the
-	// default), the Gateway will not act as a default Gateway; if set, the
+	// DefaultScope defines the default scope for this Gateway. If unset or
+	// set to the empty string `""` (the default), the Gateway will not
+	// act as a default Gateway; if set, the
 	// Gateway will claim any Route with a matching scope set in its
 	// UseDefaultGateway field, subject to the usual rules about which routes
 	// the Gateway can attach to.

apis/v1/shared_types.go

@@ -247,8 +247,14 @@ type CommonRouteSpec struct {
 	// supporting the named scope, subject to the usual rules about which
 	// Routes a Gateway is allowed to claim.
 	//
-	// +optional
-	// <gateway:experimental>
+	// Think carefully before using this functionality! The set of default
+	// Gateways supporting the requested scope can change over time without
+	// any notice to the Route author, and in many situations it will not be
+	// appropriate to request a default Gateway for a given Route -- for
+	// example, a Route with specific security needs should almost certainly
+	// not use a default Gateway.
+	//
+	// +optional <gateway:experimental>
 	UseDefaultGateway GatewayDefaultScope `json:"useDefaultGateway,omitempty"`
 }