From cfa160d3321839a5b42fc9fda0911f634518ac8b Mon Sep 17 00:00:00 2001
From: Gabe Rosenhouse <grosenhouse@vmware.com>
Date: Tue, 6 Oct 2020 20:04:35 -0700
Subject: [PATCH] document NamedAddress

---
 apis/v1alpha1/gateway_types.go | 9 ++++++---
 docs-src/spec.md               | 5 +++--
 docs/spec/index.html           | 5 +++--
 3 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/apis/v1alpha1/gateway_types.go b/apis/v1alpha1/gateway_types.go
index 08c2a6f7b3..7d3e51359a 100644
--- a/apis/v1alpha1/gateway_types.go
+++ b/apis/v1alpha1/gateway_types.go
@@ -484,8 +484,11 @@ type GatewayAddress struct {
 // AddressType defines how a network address is represented as a text string.
 // Valid AddressType values are:
 //
-// * "IPAddress"
-// * "NamedAddress"
+// * "IPAddress": an IPv4 or IPv6 address
+// * "NamedAddress": an opauqe identifier. The interpretation of
+//   the name is dependent on the controller.
+//
+// A NamedAddress might be a cloud-dependent ID for a "static" or "elastic" IP
 //
 // +kubebuilder:validation:Enum=IPAddress;NamedAddress
 type AddressType string
@@ -503,7 +506,7 @@ const (
 	// Support: Extended.
 	IPAddressType AddressType = "IPAddress"
 
-	// NamedAddressType is an address selected by name. The interpretation
+	// NamedAddressType is an opaque identifier. The interpretation
 	// of the name is dependent on the controller. If a NamedAddress is
 	// requested but unsupported by an implementation, the controller
 	// should raise the "Detached" listener status condition on the Gateway
diff --git a/docs-src/spec.md b/docs-src/spec.md
index 1119b90108..ac04a742e5 100644
--- a/docs-src/spec.md
+++ b/docs-src/spec.md
@@ -891,9 +891,10 @@ UDPRouteStatus
 <p>AddressType defines how a network address is represented as a text string.
 Valid AddressType values are:</p>
 <ul>
-<li>&ldquo;IPAddress&rdquo;</li>
-<li>&ldquo;NamedAddress&rdquo;</li>
+<li>&ldquo;IPAddress&rdquo;: an IPv4 or IPv6 address</li>
+<li>&ldquo;NamedAddress&rdquo;: an opaque identifier, controller-dependent</li>
 </ul>
+<p>A NamedAddress might be a cloud-dependent ID for a &ldquo;static&rdquo; or &ldquo;elastic&rdquo; IP</p>
 </p>
 <h3 id="networking.x-k8s.io/v1alpha1.BackendPolicyConditionType">BackendPolicyConditionType
 (<code>string</code> alias)</p></h3>
diff --git a/docs/spec/index.html b/docs/spec/index.html
index 760d7fd42a..b3d4dd4b2f 100644
--- a/docs/spec/index.html
+++ b/docs/spec/index.html
@@ -1422,9 +1422,10 @@ <h3 id="networking.x-k8s.io/v1alpha1.AddressType">AddressType
 <p>AddressType defines how a network address is represented as a text string.
 Valid AddressType values are:</p>
 <ul>
-<li>&ldquo;IPAddress&rdquo;</li>
-<li>&ldquo;NamedAddress&rdquo;</li>
+<li>&ldquo;IPAddress&rdquo;: an IPv4 or IPv6 address</li>
+<li>&ldquo;NamedAddress&rdquo;: an opaque identifier, controller-dependent</li>
 </ul>
+<p>A NamedAddress might be a cloud-dependent ID for a &ldquo;static&rdquo; or &ldquo;elastic&rdquo; IP</p>
 </p>
 <h3 id="networking.x-k8s.io/v1alpha1.BackendPolicyConditionType">BackendPolicyConditionType
 (<code>string</code> alias)</p></h3>