Convert Go field and type names in autogenerated API docs · Issue #19319 · kubernetes/kubernetes (original) (raw)

We autogenerate user-facing API documentation from types.go comments now. Most people tend to refer to Go field and type names in their comments as per typical godoc style. However, this isn't appropriate for user docs. I generally tell people to use the json field names instead of Go field names and English instead of type names, but it's been an uphill battle to enforce.

When generating documentation in WriteSwaggerDocFunc, we should try to automatically convert Go field and type names in the comments to json field names and English rather than type names. ParseDocumentationFrom keeps the json field names but discards the Go field names. In general, they should be the same except for capitalization of the first letter, but we could also just keep both in KubeTypes, and replace all occurrences of the Go field name with the json field name in the Doc string. For the type names, we could replace all occurrences of the Go type name with the type name split into separate words at capital letters. For example, ReplicaSetSpec would become Replica Set Spec. That's not ideal, but Horizontal Pod Autoscaler List would be better than HorizontalPodAutoscalerList.