Refactor godocs for API fields to start with the serialised versions

[chrischdi]

What would you like to be added (User Story)?

Godocs for api types in core k8s normally start with the serialised version for better readability in e.g. kubectl describe.

Example:

	// emptyDir represents a temporary directory that shares a pod's lifetime.
	// More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
	// +optional
	EmptyDir *EmptyDirVolumeSource `json:"emptyDir,omitempty" protobuf:"bytes,2,opt,name=emptyDir"`

Source: https://github.com/kubernetes/api/blob/master/core/v1/types.go#L60-L63

This issue tracks refactoring all relevant godocs of our API types.

Maybe there could also be a linter to enforce this.

Detailed Description

I can't see it explicitly called out in the API conventions from upstream, but, take a look at the godoc across the core types (and I know the upstream API reviewers enforce this from experience), kubernetes/api@master/core/v1/types.go, all of the godocs on fields start with the json tag version of the field name, so that when docs are generated, they represent the serialised versions of the strings

[0]

Anything else you would like to add?

xref: Discussion at #11166 (comment)

Label(s) to be applied

/kind api

[k8s-ci-robot]

@chrischdi: The label(s) kind/api cannot be applied, because the repository doesn't have them.

In response to this:

What would you like to be added (User Story)?

Godocs for api types in core k8s normally start with the serialised version for better readability in e.g. kubectl describe.

Example:

  // emptyDir represents a temporary directory that shares a pod's lifetime.
  // More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
  // +optional
  EmptyDir *EmptyDirVolumeSource `json:"emptyDir,omitempty" protobuf:"bytes,2,opt,name=emptyDir"`

Source: https://github.com/kubernetes/api/blob/master/core/v1/types.go#L60-L63

This issue tracks refactoring all relevant godocs of our API types.

Maybe there could also be a linter to enforce this.

Detailed Description

I can't see it explicitly called out in the API conventions from upstream, but, take a look at the godoc across the core types (and I know the upstream API reviewers enforce this from experience), kubernetes/api@master/core/v1/types.go, all of the godocs on fields start with the json tag version of the field name, so that when docs are generated, they represent the serialised versions of the strings

[0]

Anything else you would like to add?

xref: Discussion at #11166 (comment)

Label(s) to be applied

/kind api

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-sigs/prow repository.

[sbueringer]

Sounds good to me!

(cc @vincepri @fabriziopandini @JoelSpeed)

/kind cleanup
/priority backlog
/triage accepted
/help

[k8s-ci-robot]

@sbueringer:
This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

Sounds good to me!

(cc @vincepri @fabriziopandini @JoelSpeed)

/kind cleanup
/priority backlog
/triage accepted
/help

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-sigs/prow repository.