Make an editorial pass over the API documentation.

Especially now that enum constants are rendered in the HTML API
documentation, the godoc conventions make it harder for a reader
to understand the intentions of the documentation.

To handle passing a literal "*" character through the two layers of
Markdown, we postprocess the`"*"` pattern into a HTML entity.

Make an editorial pass that improves readability without any semantic
changes.

Signed-off-by: James Peach <jpeach@vmware.com>

Makefile

@@ -68,8 +68,9 @@ verify:
 # Build the documentation.
 .PHONY: docs
 docs:
-	# Generate API docs first
-	./hack/api-docs/generate.sh docs-src/spec.md
+	# Generate API docs first. Hack markdown rendering of literal "*"
+	# characters so we don't have so use HTML entities in godoc.
+	./hack/api-docs/generate.sh /dev/stdout | sed '-es|"*\*|\"\*|g' > docs-src/spec.md
 	# The docs image must be built locally until issue #141 is fixed.
 	docker build --tag k8s.gcr.io/gateway-api-mkdocs:latest -f mkdocs.dockerfile .
 	$(MAKE) -f docs.mk

apis/v1alpha1/backendpolicy_types.go

@@ -116,7 +116,7 @@ type BackendTLSConfig struct {
 	// Options are a list of key/value pairs to give extended options to the
 	// provider.
 	//
-	// Support: Implementation-specific.
+	// Support: Implementation-specific
 	//
 	// +optional
 	Options map[string]string `json:"options,omitempty"`
@@ -134,12 +134,11 @@ type BackendPolicyStatus struct {
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 }
 
-// BackendPolicyConditionType is a type of condition associated with a
-// BackendPolicy.
+// BackendPolicyConditionType is a type of condition used to express the current
+// state of a BackendPolicy resource.
 type BackendPolicyConditionType string
 
 const (
-	// ConditionNoSuchBackend indicates that one or more of the the specified
-	// Backends does not exist.
+	// Indicates that one or more of the the specified backend references could not be resolved.
 	ConditionNoSuchBackend BackendPolicyConditionType = "NoSuchBackend"
 )