Merge pull request #1690 from bvwells/controller-docs

✨ add comments for the exported methods in generated controllers (only v3+)

pkg/plugin/v3/scaffolds/api.go

@@ -112,7 +112,7 @@ func (s *apiScaffolder) scaffold() error {
 		if err := machinery.NewScaffold(s.plugins...).Execute(
 			s.newUniverse(),
 			&controller.SuiteTest{},
-			&controller.Controller{},
+			&controller.Controller{ControllerRuntimeVersion: ControllerRuntimeVersion},
 		); err != nil {
 			return fmt.Errorf("error scaffolding controller: %v", err)
 		}

pkg/plugin/v3/scaffolds/internal/templates/config/controller/controller.go

@@ -31,6 +31,8 @@ type Controller struct {
 	file.MultiGroupMixin
 	file.BoilerplateMixin
 	file.ResourceMixin
+
+	ControllerRuntimeVersion string
 }
 
 // SetTemplateDefaults implements input.Template
@@ -81,6 +83,15 @@ type {{ .Resource.Kind }}Reconciler struct {
 // +kubebuilder:rbac:groups={{ .Resource.Domain }},resources={{ .Resource.Plural }}/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups={{ .Resource.Domain }},resources={{ .Resource.Plural }}/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the {{ .Resource.Kind }} object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@{{ .ControllerRuntimeVersion }}/pkg/reconcile
 func (r *{{ .Resource.Kind }}Reconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("{{ .Resource.Kind | lower }}", req.NamespacedName)
@@ -90,6 +101,7 @@ func (r *{{ .Resource.Kind }}Reconciler) Reconcile(req ctrl.Request) (ctrl.Resul
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *{{ .Resource.Kind }}Reconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&{{ .Resource.ImportAlias }}.{{ .Resource.Kind }}{}).

testdata/project-v3-multigroup/controllers/crew/captain_controller.go

@@ -38,6 +38,15 @@ type CaptainReconciler struct {
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=captains/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=captains/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Captain object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *CaptainReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("captain", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *CaptainReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *CaptainReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&crewv1.Captain{}).

testdata/project-v3-multigroup/controllers/foo.policy/healthcheckpolicy_controller.go

@@ -38,6 +38,15 @@ type HealthCheckPolicyReconciler struct {
 // +kubebuilder:rbac:groups=foo.policy.testproject.org,resources=healthcheckpolicies/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=foo.policy.testproject.org,resources=healthcheckpolicies/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the HealthCheckPolicy object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *HealthCheckPolicyReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("healthcheckpolicy", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *HealthCheckPolicyReconciler) Reconcile(req ctrl.Request) (ctrl.Result,
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *HealthCheckPolicyReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&foopolicyv1.HealthCheckPolicy{}).

testdata/project-v3-multigroup/controllers/lakers_controller.go

@@ -38,6 +38,15 @@ type LakersReconciler struct {
 // +kubebuilder:rbac:groups=testproject.org,resources=lakers/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=testproject.org,resources=lakers/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Lakers object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *LakersReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("lakers", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *LakersReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *LakersReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&testprojectorgv1.Lakers{}).

testdata/project-v3-multigroup/controllers/sea-creatures/kraken_controller.go

@@ -38,6 +38,15 @@ type KrakenReconciler struct {
 // +kubebuilder:rbac:groups=sea-creatures.testproject.org,resources=krakens/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=sea-creatures.testproject.org,resources=krakens/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Kraken object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *KrakenReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("kraken", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *KrakenReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *KrakenReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&seacreaturesv1beta1.Kraken{}).

testdata/project-v3-multigroup/controllers/sea-creatures/leviathan_controller.go

@@ -38,6 +38,15 @@ type LeviathanReconciler struct {
 // +kubebuilder:rbac:groups=sea-creatures.testproject.org,resources=leviathans/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=sea-creatures.testproject.org,resources=leviathans/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Leviathan object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *LeviathanReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("leviathan", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *LeviathanReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *LeviathanReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&seacreaturesv1beta2.Leviathan{}).

testdata/project-v3-multigroup/controllers/ship/cruiser_controller.go

@@ -38,6 +38,15 @@ type CruiserReconciler struct {
 // +kubebuilder:rbac:groups=ship.testproject.org,resources=cruisers/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=ship.testproject.org,resources=cruisers/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Cruiser object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *CruiserReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("cruiser", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *CruiserReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *CruiserReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&shipv2alpha1.Cruiser{}).

testdata/project-v3-multigroup/controllers/ship/destroyer_controller.go

@@ -38,6 +38,15 @@ type DestroyerReconciler struct {
 // +kubebuilder:rbac:groups=ship.testproject.org,resources=destroyers/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=ship.testproject.org,resources=destroyers/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Destroyer object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *DestroyerReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("destroyer", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *DestroyerReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *DestroyerReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&shipv1.Destroyer{}).

testdata/project-v3-multigroup/controllers/ship/frigate_controller.go

@@ -38,6 +38,15 @@ type FrigateReconciler struct {
 // +kubebuilder:rbac:groups=ship.testproject.org,resources=frigates/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=ship.testproject.org,resources=frigates/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Frigate object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *FrigateReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("frigate", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *FrigateReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *FrigateReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&shipv1beta1.Frigate{}).

testdata/project-v3/controllers/admiral_controller.go

@@ -38,6 +38,15 @@ type AdmiralReconciler struct {
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=admirals/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=admirals/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Admiral object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *AdmiralReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("admiral", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *AdmiralReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *AdmiralReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&crewv1.Admiral{}).

testdata/project-v3/controllers/captain_controller.go

@@ -38,6 +38,15 @@ type CaptainReconciler struct {
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=captains/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=captains/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the Captain object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *CaptainReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("captain", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *CaptainReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *CaptainReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&crewv1.Captain{}).

testdata/project-v3/controllers/firstmate_controller.go

@@ -38,6 +38,15 @@ type FirstMateReconciler struct {
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=firstmates/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=crew.testproject.org,resources=firstmates/finalizers,verbs=update
 
+// Reconcile is part of the main kubernetes reconciliation loop which aims to
+// move the current state of the cluster closer to the desired state.
+// TODO(user): Modify the Reconcile function to compare the state specified by
+// the FirstMate object against the actual cluster state, and then
+// perform operations to make the cluster state reflect the state specified by
+// the user.
+//
+// For more details, check Reconcile and its Result here:
+// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.6.3/pkg/reconcile
 func (r *FirstMateReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	_ = context.Background()
 	_ = r.Log.WithValues("firstmate", req.NamespacedName)
@@ -47,6 +56,7 @@ func (r *FirstMateReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
 	return ctrl.Result{}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *FirstMateReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&crewv1.FirstMate{}).