controller: add missing documentation comments

Adds documentation comments to exported types and methods in the controller
packages to comply with Go style guidelines requiring all exported identifiers
to be documented.

Updates:
- MultigresClusterReconciler: Added docs for struct and methods.
- TableGroupReconciler: Added docs for struct and methods.
- TemplateResolver: Added docs for struct, resolve methods, and merge logic helpers.
- Reordered Kubebuilder markers to appear after the documentation comments, ensuring correct summary generation in godoc.

Author: fernando-villalba

pkg/cluster-handler/controller/multigrescluster/multigrescluster_controller.go

@@ -23,18 +23,21 @@ const (
 	finalizerName = "multigres.com/finalizer"
 )
 
+// MultigresClusterReconciler reconciles a MultigresCluster object.
 type MultigresClusterReconciler struct {
 	client.Client
 	Scheme *runtime.Scheme
 }
 
+// Reconcile reads that state of the cluster for a MultigresCluster object and makes changes based on the state read
+// and what is in the MultigresCluster.Spec.
+//
 // +kubebuilder:rbac:groups=multigres.com,resources=multigresclusters,verbs=get;list;watch;create;update;patch;delete
 // +kubebuilder:rbac:groups=multigres.com,resources=multigresclusters/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=multigres.com,resources=multigresclusters/finalizers,verbs=update
 // +kubebuilder:rbac:groups=multigres.com,resources=coretemplates;celltemplates;shardtemplates,verbs=get;list;watch
 // +kubebuilder:rbac:groups=multigres.com,resources=cells;tablegroups;toposervers,verbs=get;list;watch;create;update;patch;delete
 // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
-
 func (r *MultigresClusterReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 	l := log.FromContext(ctx)
 
@@ -455,6 +458,7 @@ func (r *MultigresClusterReconciler) updateStatus(ctx context.Context, cluster *
 	return r.Status().Update(ctx, cluster)
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *MultigresClusterReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&multigresv1alpha1.MultigresCluster{}).

pkg/cluster-handler/controller/multigrescluster/template_logic.go

@@ -11,13 +11,17 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
-// TemplateResolver handles the logic for fetching and merging templates
+// TemplateResolver handles the logic for fetching and merging templates.
 type TemplateResolver struct {
-	Client    client.Client
+	// Client is the kubernetes client used to fetch templates.
+	Client client.Client
+	// Namespace is the namespace where templates are expected to exist.
 	Namespace string
-	Defaults  multigresv1alpha1.TemplateDefaults
+	// Defaults contains the cluster-level template references to use when explicit ones are missing.
+	Defaults multigresv1alpha1.TemplateDefaults
 }
 
+// ResolveCoreTemplate fetches and resolves a CoreTemplate by name, handling defaults.
 func (r *TemplateResolver) ResolveCoreTemplate(ctx context.Context, templateName string) (*multigresv1alpha1.CoreTemplate, error) {
 	name := templateName
 	if name == "" {
@@ -38,6 +42,7 @@ func (r *TemplateResolver) ResolveCoreTemplate(ctx context.Context, templateName
 	return tpl, nil
 }
 
+// ResolveCellTemplate fetches and resolves a CellTemplate by name, handling defaults.
 func (r *TemplateResolver) ResolveCellTemplate(ctx context.Context, templateName string) (*multigresv1alpha1.CellTemplate, error) {
 	name := templateName
 	if name == "" {
@@ -58,6 +63,7 @@ func (r *TemplateResolver) ResolveCellTemplate(ctx context.Context, templateName
 	return tpl, nil
 }
 
+// ResolveShardTemplate fetches and resolves a ShardTemplate by name, handling defaults.
 func (r *TemplateResolver) ResolveShardTemplate(ctx context.Context, templateName string) (*multigresv1alpha1.ShardTemplate, error) {
 	name := templateName
 	if name == "" {
@@ -78,7 +84,7 @@ func (r *TemplateResolver) ResolveShardTemplate(ctx context.Context, templateNam
 	return tpl, nil
 }
 
-// MergeCellConfig merges template spec with overrides
+// MergeCellConfig merges a template spec with overrides and an inline spec to produce the final configuration.
 func MergeCellConfig(template *multigresv1alpha1.CellTemplate, overrides *multigresv1alpha1.CellOverrides, inline *multigresv1alpha1.CellInlineSpec) (multigresv1alpha1.StatelessSpec, *multigresv1alpha1.LocalTopoServerSpec) {
 	var gateway multigresv1alpha1.StatelessSpec
 	var localTopo *multigresv1alpha1.LocalTopoServerSpec
@@ -105,7 +111,7 @@ func MergeCellConfig(template *multigresv1alpha1.CellTemplate, overrides *multig
 	return gateway, localTopo
 }
 
-// MergeShardConfig merges template spec with overrides
+// MergeShardConfig merges a template spec with overrides and an inline spec to produce the final configuration.
 func MergeShardConfig(template *multigresv1alpha1.ShardTemplate, overrides *multigresv1alpha1.ShardOverrides, inline *multigresv1alpha1.ShardInlineSpec) (multigresv1alpha1.MultiOrchSpec, map[string]multigresv1alpha1.PoolSpec) {
 	if inline != nil {
 		return inline.MultiOrch, inline.Pools
@@ -202,6 +208,7 @@ func mergePoolSpec(base multigresv1alpha1.PoolSpec, override multigresv1alpha1.P
 	return out
 }
 
+// ResolveGlobalTopo determines the final GlobalTopoServer configuration by preferring inline config over templates.
 func ResolveGlobalTopo(spec *multigresv1alpha1.GlobalTopoServerSpec, coreTemplate *multigresv1alpha1.CoreTemplate) *multigresv1alpha1.GlobalTopoServerSpec {
 	// If inline config is present, use it.
 	if spec.Etcd != nil || spec.External != nil {
@@ -218,6 +225,7 @@ func ResolveGlobalTopo(spec *multigresv1alpha1.GlobalTopoServerSpec, coreTemplat
 	return spec
 }
 
+// ResolveMultiAdmin determines the final MultiAdmin configuration by preferring inline config over templates.
 func ResolveMultiAdmin(spec *multigresv1alpha1.MultiAdminConfig, coreTemplate *multigresv1alpha1.CoreTemplate) *multigresv1alpha1.StatelessSpec {
 	// If inline spec is present, use it.
 	if spec.Spec != nil {

pkg/cluster-handler/controller/tablegroup/tablegroup_controller.go

@@ -17,15 +17,17 @@ import (
 	multigresv1alpha1 "github.com/numtide/multigres-operator/api/v1alpha1"
 )
 
+// TableGroupReconciler reconciles a TableGroup object.
 type TableGroupReconciler struct {
 	client.Client
 	Scheme *runtime.Scheme
 }
 
+// Reconcile reads the state of the TableGroup and ensures its child Shards are in the desired state.
+//
 // +kubebuilder:rbac:groups=multigres.com,resources=tablegroups,verbs=get;list;watch;create;update;patch;delete
 // +kubebuilder:rbac:groups=multigres.com,resources=tablegroups/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=multigres.com,resources=shards,verbs=get;list;watch;create;update;patch;delete
-
 func (r *TableGroupReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 	l := log.FromContext(ctx)
 
@@ -138,6 +140,7 @@ func (r *TableGroupReconciler) Reconcile(ctx context.Context, req ctrl.Request)
 	return ctrl.Result{RequeueAfter: 1 * time.Minute}, nil
 }
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *TableGroupReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&multigresv1alpha1.TableGroup{}).