gen-crd-api-reference-docs

gen-crd-api-reference-docs copied to clipboard

I posted https://github.com/kubernetes-sigs/service-apis/pull/173 to generate documentation for service-apis, and I noticed that no documentation is generated for constants of an aliased type.

For example, in the CRD definition, we have:

// GatewayConditionType is a type of condition associated with a Gateway.
type GatewayConditionType string

const (
	// ConditionNoSuchGatewayClass indicates that the specified GatewayClass
	// does not exist.
	ConditionNoSuchGatewayClass GatewayConditionType = "NoSuchGatewayClass"
	// ConditionGatewayNotScheduled indicates that the Gateway has not been
	// scheduled.
	ConditionGatewayNotScheduled GatewayConditionType = "GatewayNotScheduled"
	// ConditionListenersNotReady indicates that at least one of the specified
	// listeners is not ready. If this condition has a status of True, a more
	// detailed ListenerCondition should be present in the corresponding
	// ListenerStatus.
...
)

Documentation is generated for GatewayConditionType, but not for any of the constants that are defined for this type.

<h3 id="networking.x-k8s.io/v1alpha1.GatewayClassConditionType">GatewayClassConditionType
(<code>string</code> alias)</p></h3>
<p>
(<em>Appears on:</em>
<a href="#networking.x-k8s.io/v1alpha1.GatewayClassCondition">GatewayClassCondition</a>)
</p>
<p>
<p>GatewayClassConditionType is the type of status conditions.</p>
</p>
<h3 id="networking.x-k8s.io/v1alpha1.GatewayClassSpec">GatewayClassSpec
</h3>

At least in the way this particular API is written, the doc comments for specific condition types contain information that is useful for API consumers and implementers, so it would be great if these cold be emitted too.

gengo omits comments for constants https://github.com/kubernetes/gengo/issues/186 gengo omits the underlying value of the constant https://github.com/kubernetes/gengo/issues/187

I agree that this would be nice.