address comments

Signed-off-by: huabing zhao <zhaohuabing@gmail.com>

apis/v1alpha2/policy_types.go

@@ -16,11 +16,11 @@ limitations under the License.
 
 package v1alpha2
 
-// PolicyTargetReference identifies an API object to apply policy to. This
-// should be used as part of Policy resources that can target Gateway API
-// resources. For more information on how this policy attachment model works,
-// and a sample Policy resource, refer to the policy attachment documentation
-// for Gateway API.
+// PolicyTargetReference identifies an API object to apply a direct or
+// inherited policy to. This should be used as part of Policy resources
+// that can target Gateway API resources. For more information on how this
+// policy attachment model works, and a sample Policy resource, refer to
+// the policy attachment documentation for Gateway API.
 type PolicyTargetReference struct {
 	// Group is the group of the target resource.
 	Group Group `json:"group"`
@@ -40,19 +40,21 @@ type PolicyTargetReference struct {
 	Namespace *Namespace `json:"namespace,omitempty"`
 }
 
-// DirectPolicyTargetReference identifies an API object to apply direct policy to.
+// DirectPolicyTargetReference identifies an API object to apply a direct policy to.
 // This should be used as part of Policy resources that can target single resources.
 // For more information on how this policy attachment model works, and a sample
 // Policy resource, refer to the policy attachment documentation for Gateway API.
 //
-// Note: This should be used for direct policy attachment only.
-// <gateway:experimental>
+// Note: This should only be used for direct policy attachment when references
+// to SectionName are actually needed. In all other cases, PolicyTargetReference
+// should be used.
 type DirectPolicyTargetReference struct {
 	PolicyTargetReference `json:",inline"`
 
 	// SectionName is the name of a section within the target resource. When
 	// unspecified, this targetRef targets the entire resource. In the following
 	// resources, SectionName is interpreted as the following:
+	//
 	// * Gateway: Listener Name
 	// * Service: Port Name
 	//

geps/gep-713.md

@@ -1316,8 +1316,8 @@ spec:
     sectionName: bar
 ```
 
-This would require adding a `Name` field to those sub-resources that currently lack a name. For example,
-a `Name` field could be added to the `RouteRule` object:
+This would require adding a `name` field to those sub-resources that currently lack a name. For example,
+a `name` field could be added to the `RouteRule` object:
 ```go
 type RouteRule struct {
     // Name is the name of the Route rule. If more than one Route Rule is
@@ -1337,8 +1337,8 @@ type RouteRule struct {
 If a `sectionName` is specified, but does not exist on the targeted object, the Policy must fail to attach,
 and the policy implementation should record a `resolvedRefs` or similar Condition in the Policy's status.
 
-When multiple Policies of the same type target the same object, one with a `SectionName` specified, and one without,
-the one with a `SectionName` is more specific, and so will have all its settings apply. The less-specific Policy will
+When multiple Policies of the same type target the same object, one with a `sectionName` specified, and one without,
+the one with a `sectionName` is more specific, and so will have all its settings apply. The less-specific Policy will
 not attach to the target.
 
 Note that the `sectionName` is currently intended to be used only for Direct Policy Attachment. Inherited Policies