Fix another round of PR comments

Signed-off-by: Nick Young <ynick@vmware.com>

apis/v1alpha2/httproute_types.go

@@ -730,7 +730,7 @@ type HTTPRequestMirrorFilter struct {
 	// underlying implemenation.
 	//
 	// If there is a cross-namespace reference to an *existing* object
-	// that is not covered by a ReferencePolicy, the controller must ensure the
+	// that is not allowed by a ReferencePolicy, the controller must ensure the
 	// "ResolvedRefs"  condition on the Gateway is set to `status: true`,
 	// with the "RefNotPermitted" reason and not configure this backend in the
 	// underlying implementation.

apis/v1alpha2/object_reference_types.go

@@ -66,7 +66,8 @@ type ObjectReference struct {
 	//
 	// Note that when a namespace is specified, a ReferencePolicy object
 	// is required in the referent namespace to allow that namespace's
-	// owner to accept the reference. See the ReferencePolicy object for details.
+	// owner to accept the reference. See the ReferencePolicy documentation
+	// for details.
 	//
 	// Support: Core
 	//
@@ -82,23 +83,24 @@ type ObjectReference struct {
 //
 // Note that when a namespace is specified, a ReferencePolicy object
 // is required in the referent namespace to allow that namespace's
-// owner to accept the reference. See the ReferencePolicy object for details.
+// owner to accept the reference. See the ReferencePolicy documentation
+// for details.
 type BackendObjectReference struct {
 	// Group is the group of the referent.
 	// When unspecified (empty string), core API group is inferred.
 	//
 	// +optional
 	// +kubebuilder:default=""
 	// +kubebuilder:validation:MaxLength=253
-	Group *string `json:"group"`
+	Group *string `json:"group,omitempty"`
 
 	// Kind is kind of the referent.
 	//
 	// +optional
 	// +kubebuilder:default=Service
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
-	Kind *string `json:"kind"`
+	Kind *string `json:"kind,omitempty"`
 
 	// Name is the name of the referent.
 	//
@@ -111,7 +113,8 @@ type BackendObjectReference struct {
 	//
 	// Note that when a namespace is specified, a ReferencePolicy object
 	// is required in the referent namespace to allow that namespace's
-	// owner to accept the reference. See the ReferencePolicy object for details.
+	// owner to accept the reference. See the ReferencePolicy documentation
+	// for details.
 	//
 	// Support: Core
 	//

apis/v1alpha2/shared_types.go

@@ -82,7 +82,8 @@ type GatewayReference struct {
 //
 // Note that when a namespace is specified, a ReferencePolicy object
 // is required in the referent namespace to allow that namespace's
-// owner to accept the reference. See the ReferencePolicy object for details.
+// owner to accept the reference. See the ReferencePolicy documentation
+// for details.
 type BackendRef struct {
 	// BackendObjectReference references a Kubernetes object.
 	BackendObjectReference `json:",inline"`

site-src/v1alpha2/references/cross-namespace-references.md

@@ -1,21 +1,24 @@
 # Cross namespace references and ReferencePolicy
 
-### Terminology note
-When discussing the process of creating cross-namespace object references, this
-document and the documentation on the API itself refers to the object being
-referred to as "the referent object", using the meaning of "referent" to be
-"the person, thing, or idea that a word, phrase, or object refers to".[1](https://dictionary.cambridge.org/dictionary/english/referent)
-
 ## Introduction
 In the Gateway API, it is possible to have references between objects cross
-namespace boundaries. In particular, that Services may be referred to by Routes
+namespace boundaries. In particular, Services may be referred to by Routes
 in a another namespace, or possibly Secrets may be referred to by Gateways or
 Routes in another namespace.
 
 In the past, we've seen that forwarding traffic across namespace boundaries is a
-desired feature, but without the kinds of safeguards proposed here,
+desired feature, but a safeguard like ReferencePolicy,
 [vulnerabilities](https://github.com/kubernetes/kubernetes/issues/103675) can emerge.
 
+!!!note
+
+    When discussing the process of creating cross-namespace object references, this
+    document and the documentation on the API itself refers to the object being
+    referred to as "the referent object", using the
+    [meaning](https://dictionary.cambridge.org/dictionary/english/referent)
+    of "referent" to be "the person, thing, or idea that a word, phrase, or object
+    refers to".
+
 In order to bring cross-namespace references under the control
 of the owner of the referent object's namespace, the Gateway API has a
 ReferencePolicy object that must be created in the referent namespace for the
@@ -25,8 +28,6 @@ To put this another way, if an object is referred to from outside its namespace,
 the object's owner must create a ReferencePolicy object that describes how that
 reference is allowed. This page explains how this process works.
 
-
-
 ## ReferencePolicy
 
 To ensure that Gateway API is able to safely provide this functionality,
@@ -68,7 +69,7 @@ spec:
     kind: HTTPRoute
     namespace: foo
   to:
-  - group: core
+  - group: ""
     kind: Service
 ```