field metav1.ObjectMeta is missing godoc comment

[guettli]

.../foo_type.go:N:M: field metav1.ObjectMeta is missing godoc comment

Do you really want a godoc for ObjectMeta?

type Foo struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

I think a godoc for ObjecMeta would decrease the signal-noise-ratio in the source code.

Same for Conditions.

[JoelSpeed]

In struct: ContainerRuntimeConfig, field documentation is missing: metadata

When using the Kube swagger generator, if you are missing documentation on any field, it will report the error. I think it's fairly standard to have a comment on the ObjectMeta. It would still be displayed in kubectl describe right? You'd have a gap there if you don't have that comment.

I normally just recommend:

// metadata is the standard object's metadata.

And if you look at the k8s swagger you can see they have similar on all of their ObjectMeta.

Same for Conditions.

Conditions should absolutely be documented, the same as any other status field. Typically they'll document the expected types of conditions.

// conditions represents the current state of the Foo object.
// Known condition types are Bar, Baz and Ready.

[guettli]

Thank you for your answer. I still feel new to controller development. I usually stick to the kubebuilder book, and consider it best practice.

This is not a big problem, but in the long run I think it would be good if code based on the kubebuilder book does not generate warnings.

But this is not an issue of KAL, it is an issue of kubebuilder. I am unsure if they have the same goal.

Closing this. Cleaning up the examples of kubebuilder is a different topic.

[JoelSpeed]

I think there will be interest from the kubebuilder maintainers to make sure that KALs default configuration doesn't report any issues, we should definitely create an issue for them

[everettraven]

Better yet, we should open an issue about integrating kube-api-linter into the makefile that is generated for new operators by Kubebuilder.

[JoelSpeed]

Continuing the discussion in kubernetes-sigs/kubebuilder#4809 now