Type aliases resolve too aggressively in the generated API documentation

[jpeach]

What happened:

All the type aliases for ConfigMapsDefaultLocalObjectReference end up linking back to a single documentation block. We lose the unique documentation present at each alias declaration.

Fields that are an instance of the type alias are also collapsed into the underlying type, which is not what we want.

What you expected to happen:

Each type alias should get its own documentation block, ie. for each of these:

api/v1alpha1/gateway_types.go:type ListenerExtensionObjectReference = ConfigMapsDefaultLocalObjectReference
api/v1alpha1/gatewayclass_types.go:type GatewayClassParametersObjectReference = ConfigMapsDefaultLocalObjectReference
api/v1alpha1/httproute_types.go:type RouteMatchExtensionObjectReference = ConfigMapsDefaultLocalObjectReference
api/v1alpha1/httproute_types.go:type RouteFilterExtensionObjectReference = ConfigMapsDefaultLocalObjectReference
api/v1alpha1/httproute_types.go:type RouteActionExtensionObjectReference = ConfigMapsDefaultLocalObjectReference
api/v1alpha1/httproute_types.go:type RouteHostExtensionObjectReference = ConfigMapsDefaultLocalObjectReference

[bowei]

This looks to be a consequence of how type aliases behave in Golang. They don't show up as actual types.
Maybe it's better to just reuse the same type instead of alias for the time being?

[jpeach]

xref ahmetb/gen-crd-api-reference-docs#23

[jpeach]

This looks to be a consequence of how type aliases behave in Golang. They don't show up as actual types.

The generator is using gengo, so I think that it can distinguish type aliases in the source.

Maybe it's better to just reuse the same type instead of alias for the time being?

One thing I was playing with is inlining the type rather than aliasing. This probably gets the same result in YAML, JSON and Go, but not in protobuf.

diff --git api/v1alpha1/httproute_types.go api/v1alpha1/httproute_types.go
index e290acc..ba22865 100644
--- api/v1alpha1/httproute_types.go
+++ api/v1alpha1/httproute_types.go
@@ -273,7 +273,9 @@ type TargetPort int32
 // route action within a known namespace.
 //
 // +k8s:deepcopy-gen=false
-type ForwardToTargetObjectReference = ServicesDefaultLocalObjectReference
+type ForwardToTargetObjectReference struct {
+       ServicesDefaultLocalObjectReference `json:",inline" protobuf:"bytes,1,opt,name=servicesDefaultLocalObjectReference"`
+}

 // RouteActionExtensionObjectReference identifies a route-action extension
 // object within a known namespace.

[jpeach]

I filed kubernetes/gengo#180 for gengo. I agree that we should probably look for a local workaround.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[robscott]

may be fixed by changing
type ForwardToTargetObjectReference = ServicesDefaultLocalObjectReference
to
type ForwardToTargetObjectReference ServicesDefaultLocalObjectReference

[robscott]

/assign @bowei

[hbagdi]

#378
/close

[k8s-ci-robot]

@hbagdi: Closing this issue.

In response to this:

#378
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.