From c119ec13db217caa1a72567f2fc225aea57bb5c0 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Fri, 14 Feb 2025 11:36:53 -0500 Subject: [PATCH] fix: Add Markers and Move Comments for API Docs Update our code comment markers and copyright notice placement so that the elastic/crd-ref-docs tool can generate API reference docs: - Add `kubebuilder:object:root=true` marker for root CRD types. The crd-ref-docs tool looks for these to identify new `Kind` APIs. - Move copyright comments so they are not mistaken for package-level docs. Note - this only applies to the `v1beta1` API. Signed-off-by: Adam Kaplan --- pkg/apis/build/v1beta1/build_types.go | 6 ++++-- pkg/apis/build/v1beta1/buildrun_types.go | 6 ++++-- pkg/apis/build/v1beta1/buildstrategy_types.go | 6 ++++-- pkg/apis/build/v1beta1/clusterbuildstrategy_types.go | 6 ++++-- pkg/apis/build/v1beta1/register.go | 3 --- pkg/apis/build/v1beta1/trigger.go | 1 + pkg/apis/build/v1beta1/trigger_types.go | 1 + pkg/apis/build/v1beta1/trigger_when.go | 1 + 8 files changed, 19 insertions(+), 11 deletions(-) diff --git a/pkg/apis/build/v1beta1/build_types.go b/pkg/apis/build/v1beta1/build_types.go index 73822614b4..dff003e6c2 100644 --- a/pkg/apis/build/v1beta1/build_types.go +++ b/pkg/apis/build/v1beta1/build_types.go @@ -317,8 +317,7 @@ type BuildStatus struct { // +genclient // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object - -// Build is the Schema representing a Build definition +// +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:storageversion // +kubebuilder:resource:path=builds,scope=Namespaced @@ -327,6 +326,8 @@ type BuildStatus struct { // +kubebuilder:printcolumn:name="BuildStrategyKind",type="string",JSONPath=".spec.strategy.kind",description="The BuildStrategy type which is used for this Build" // +kubebuilder:printcolumn:name="BuildStrategyName",type="string",JSONPath=".spec.strategy.name",description="The BuildStrategy name which is used for this Build" // +kubebuilder:printcolumn:name="CreationTime",type="date",JSONPath=".metadata.creationTimestamp",description="The create time of this Build" + +// Build is the Schema representing a Build definition type Build struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -336,6 +337,7 @@ type Build struct { } // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true // BuildList contains a list of Build type BuildList struct { diff --git a/pkg/apis/build/v1beta1/buildrun_types.go b/pkg/apis/build/v1beta1/buildrun_types.go index af2882fbb8..cc3b8461da 100644 --- a/pkg/apis/build/v1beta1/buildrun_types.go +++ b/pkg/apis/build/v1beta1/buildrun_types.go @@ -268,8 +268,7 @@ type FailureDetails struct { // +genclient // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object - -// BuildRun is the Schema representing an instance of build execution +// +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:storageversion // +kubebuilder:resource:path=buildruns,scope=Namespaced,shortName=br;brs @@ -277,6 +276,8 @@ type FailureDetails struct { // +kubebuilder:printcolumn:name="Reason",type="string",JSONPath=".status.conditions[?(@.type==\"Succeeded\")].reason",description="The Succeeded reason of the BuildRun" // +kubebuilder:printcolumn:name="StartTime",type="date",JSONPath=".status.startTime",description="The start time of this BuildRun" // +kubebuilder:printcolumn:name="CompletionTime",type="date",JSONPath=".status.completionTime",description="The completion time of this BuildRun" + +// BuildRun is the Schema representing an instance of build execution type BuildRun struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -286,6 +287,7 @@ type BuildRun struct { } // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true // BuildRunList contains a list of BuildRun type BuildRunList struct { diff --git a/pkg/apis/build/v1beta1/buildstrategy_types.go b/pkg/apis/build/v1beta1/buildstrategy_types.go index 1613164c7d..8db6cabe81 100644 --- a/pkg/apis/build/v1beta1/buildstrategy_types.go +++ b/pkg/apis/build/v1beta1/buildstrategy_types.go @@ -23,11 +23,12 @@ const ( // +genclient // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object - -// BuildStrategy is the Schema representing a strategy in the namespace scope to build images from source code. +// +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:storageversion // +kubebuilder:resource:path=buildstrategies,scope=Namespaced,shortName=bs;bss + +// BuildStrategy is the Schema representing a strategy in the namespace scope to build images from source code. type BuildStrategy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -37,6 +38,7 @@ type BuildStrategy struct { } // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true // BuildStrategyList contains a list of BuildStrategy type BuildStrategyList struct { diff --git a/pkg/apis/build/v1beta1/clusterbuildstrategy_types.go b/pkg/apis/build/v1beta1/clusterbuildstrategy_types.go index c6c612c391..1f1a5917a2 100644 --- a/pkg/apis/build/v1beta1/clusterbuildstrategy_types.go +++ b/pkg/apis/build/v1beta1/clusterbuildstrategy_types.go @@ -24,11 +24,12 @@ const ( // +genclient // +genclient:nonNamespaced // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object - -// ClusterBuildStrategy is the Schema representing a strategy in the cluster scope to build images from source code. +// +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:storageversion // +kubebuilder:resource:path=clusterbuildstrategies,scope=Cluster,shortName=cbs;cbss + +// ClusterBuildStrategy is the Schema representing a strategy in the cluster scope to build images from source code. type ClusterBuildStrategy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -38,6 +39,7 @@ type ClusterBuildStrategy struct { } // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +kubebuilder:object:root=true // ClusterBuildStrategyList contains a list of ClusterBuildStrategy type ClusterBuildStrategyList struct { diff --git a/pkg/apis/build/v1beta1/register.go b/pkg/apis/build/v1beta1/register.go index b23dbfe467..f7d89bdebc 100644 --- a/pkg/apis/build/v1beta1/register.go +++ b/pkg/apis/build/v1beta1/register.go @@ -4,9 +4,6 @@ // NOTE: Boilerplate only. Ignore this file. -// Package v1beta1 contains API Schema definitions for the build v1beta1 API group -// +k8s:deepcopy-gen=package,register -// +groupName=shipwright.io package v1beta1 import ( diff --git a/pkg/apis/build/v1beta1/trigger.go b/pkg/apis/build/v1beta1/trigger.go index 633417b3be..9f8367d443 100644 --- a/pkg/apis/build/v1beta1/trigger.go +++ b/pkg/apis/build/v1beta1/trigger.go @@ -1,6 +1,7 @@ // Copyright The Shipwright Contributors // // SPDX-License-Identifier: Apache-2.0 + package v1beta1 // Trigger represents the webhook trigger configuration for a Build. diff --git a/pkg/apis/build/v1beta1/trigger_types.go b/pkg/apis/build/v1beta1/trigger_types.go index ea6550f767..065720c98c 100644 --- a/pkg/apis/build/v1beta1/trigger_types.go +++ b/pkg/apis/build/v1beta1/trigger_types.go @@ -1,6 +1,7 @@ // Copyright The Shipwright Contributors // // SPDX-License-Identifier: Apache-2.0 + package v1beta1 // TriggerType set of TriggerWhen valid names. diff --git a/pkg/apis/build/v1beta1/trigger_when.go b/pkg/apis/build/v1beta1/trigger_when.go index 1617c0b147..3fef49f256 100644 --- a/pkg/apis/build/v1beta1/trigger_when.go +++ b/pkg/apis/build/v1beta1/trigger_when.go @@ -1,6 +1,7 @@ // Copyright The Shipwright Contributors // // SPDX-License-Identifier: Apache-2.0 + package v1beta1 // TriggerWhen a given scenario where the webhook trigger is applicable.