WIP: Simplify godocs on APIs

[rikatz]

What type of PR is this?
/kind cleanup
/kind documentation

What this PR does / why we need it:

This PR simplifies the exposed Godocs, moving user facing comments and implementers guides to proper places to reduce the burden of a user when reading the API docs, while making the docs still useful.

This is a WIP, written by claude based on the Documentation design and I wanted to see how far the changes would go. This is still to be (heavily) discussed

Which issue(s) this PR fixes:

Fixes #

Does this PR introduce a user-facing change?:

Simplify the user exposed API documentations

Claude Summary

Reorganize Gateway API godoc comments to separate user-facing documentation
from implementation details using <gateway:util:excludeFromCRD> tags.

User-facing text (what a field does, valid values, support level) stays visible
in CRDs, kubectl explain, and API references. Implementation details
(conditions to set, error handling, precedence rules, reconciliation behavior)
move behind the tags — still visible in Go source and go doc, but stripped
from generated CRDs.

Changes

30 changes across 5 files in apis/v1/:

• gateway_types.go — 11 fields: Listeners, Hostname, AllowedRoutes,
  ProtocolType, ClientCertificateRef, CertificateRefs, CACertificateRefs,
  Value, Addresses, SupportedKinds, AttachedRoutes
• httproute_types.go — 8 fields: Hostnames, Matches, Filters, BackendRefs,
  Type, BackendRef (mirror), BackendRef (backend), ExternalAuthProtocol
• grpcroute_types.go — 6 fields: Hostnames, Matches, Filters, BackendRefs,
  Type, BackendRef
• backendtlspolicy_types.go — 2 fields: TargetRefs, CACertificateRefs
• shared_types.go — 3 fields: SectionName, Port, ParentRefs

Not changed (struct-level comments): GatewayClass and GRPCRoute type
descriptions were left as-is because the CRD generator only processes
excludeFromCRD tags on field descriptions, not on type-level descriptions.

CRD Size Reduction

CRD	Before	After	Saved	%
backendtlspolicies	78,552	67,944	10,608	13.5%
gatewayclasses	23,259	23,259	0	0%
gateways	188,718	146,274	42,444	22.5%
grpcroutes	122,706	111,242	11,464	9.3%
httproutes	429,092	402,156	26,936	6.3%
listenersets	42,618	42,162	456	1.1%
referencegrants	14,852	14,852	0	0%
tlsroutes	120,610	108,727	11,883	9.8%
Total	1,020,407	916,616	103,791	10.2%

Constraints

• No semantic changes — documentation content is only reorganized
• Blank lines and formatting preserved
• No kubebuilder marker changes
• All text remains in Go source (visible via go doc)

[k8s-ci-robot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[rikatz]

/hold

[rikatz]

/approve cancel

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign thockin for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment