api: add documentation comments to exported fields

Adds missing documentation comments to exported fields in the v1alpha1 API
to comply with Go style guidelines requiring all exported identifiers to be documented.

Updates:
- Shard: ShardSpec, ShardStatus, and ShardImages.
- TableGroup: TableGroupSpec, ShardResolvedSpec, and TableGroupStatus.
- Cell: CellStatus and TopologyReconciliation.
- TopoServer: GlobalTopoServerRef.

Author: fernando-villalba

api/v1alpha1/cell_types.go

@@ -71,7 +71,10 @@ type CellSpec struct {
 
 // TopologyReconciliation defines flags for the cell controller.
 type TopologyReconciliation struct {
+	// RegisterCell indicates if the cell should register itself in the topology.
 	RegisterCell bool `json:"registerCell"`
+
+	// PrunePoolers indicates if unused poolers should be removed.
 	PrunePoolers bool `json:"prunePoolers"`
 }
 
@@ -85,8 +88,13 @@ type CellStatus struct {
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	GatewayReplicas      int32 `json:"gatewayReplicas"`
+	// GatewayReplicas is the total number of gateway pods.
+	GatewayReplicas int32 `json:"gatewayReplicas"`
+
+	// GatewayReadyReplicas is the number of gateway pods that are ready.
 	GatewayReadyReplicas int32 `json:"gatewayReadyReplicas"`
+
+	// GatewayServiceName is the DNS name of the gateway service.
 	// +kubebuilder:validation:MaxLength=253
 	GatewayServiceName string `json:"gatewayServiceName,omitempty"`
 }

api/v1alpha1/shard_types.go

@@ -83,34 +83,44 @@ type PoolSpec struct {
 
 // ShardSpec defines the desired state of Shard.
 type ShardSpec struct {
+	// DatabaseName is the name of the logical database this shard belongs to.
 	// +kubebuilder:validation:MaxLength=63
 	DatabaseName string `json:"databaseName"`
+
+	// TableGroupName is the name of the table group this shard belongs to.
 	// +kubebuilder:validation:MaxLength=63
 	TableGroupName string `json:"tableGroupName"`
+
+	// ShardName is the specific identifier for this shard (e.g. "0").
 	// +kubebuilder:validation:MaxLength=63
 	ShardName string `json:"shardName"`
 
-	// Images required.
+	// Images defines the container images to be used by this shard (defined globally at MultigresCluster).
 	Images ShardImages `json:"images"`
 
-	// GlobalTopoServer reference.
+	// GlobalTopoServer is a reference to the global topology server.
 	GlobalTopoServer GlobalTopoServerRef `json:"globalTopoServer"`
 
-	// MultiOrch fully resolved spec.
+	// MultiOrch is the fully resolved configuration for the shard orchestrator.
 	MultiOrch MultiOrchSpec `json:"multiorch"`
 
-	// Pools fully resolved spec.
+	// Pools is the map of fully resolved data pool configurations.
 	// +kubebuilder:validation:MaxProperties=32
 	// +kubebuilder:validation:XValidation:rule="self.all(key, size(key) < 63)",message="pool names must be < 63 chars"
 	Pools map[string]PoolSpec `json:"pools"`
 }
 
 // ShardImages defines the images required for a Shard.
 type ShardImages struct {
+	// MultiOrch is the image for the shard orchestrator.
 	// +kubebuilder:validation:MaxLength=512
 	MultiOrch string `json:"multiorch"`
+
+	// MultiPooler is the image for the connection pooler sidecar.
 	// +kubebuilder:validation:MaxLength=512
 	MultiPooler string `json:"multipooler"`
+
+	// Postgres is the image for the postgres database.
 	// +kubebuilder:validation:MaxLength=512
 	Postgres string `json:"postgres"`
 }
@@ -130,7 +140,10 @@ type ShardStatus struct {
 	// +kubebuilder:validation:MaxItems=100
 	Cells []CellName `json:"cells,omitempty"`
 
-	OrchReady  bool `json:"orchReady"`
+	// OrchReady indicates if the MultiOrch component is ready.
+	OrchReady bool `json:"orchReady"`
+
+	// PoolsReady indicates if all data pools are ready.
 	PoolsReady bool `json:"poolsReady"`
 }
 

api/v1alpha1/tablegroup_types.go

@@ -29,19 +29,22 @@ import (
 
 // TableGroupSpec defines the desired state of TableGroup.
 type TableGroupSpec struct {
+	// DatabaseName is the name of the logical database.
 	// +kubebuilder:validation:MaxLength=63
 	DatabaseName string `json:"databaseName"`
+
+	// TableGroupName is the name of this table group.
 	// +kubebuilder:validation:MaxLength=63
 	TableGroupName string `json:"tableGroupName"`
 
 	// IsDefault indicates if this is the default/unsharded group for the database.
 	// +optional
 	IsDefault bool `json:"default,omitempty"`
 
-	// Images required for child shards.
+	// Images defines the container images used for child shards - defined globally in MultigresCluster.
 	Images ShardImages `json:"images"`
 
-	// GlobalTopoServer reference.
+	// GlobalTopoServer is a reference to the global topology server.
 	GlobalTopoServer GlobalTopoServerRef `json:"globalTopoServer"`
 
 	// Shards is the list of FULLY RESOLVED shard specifications.
@@ -52,13 +55,14 @@ type TableGroupSpec struct {
 // ShardResolvedSpec represents the fully calculated spec for a shard,
 // pushed down to the TableGroup.
 type ShardResolvedSpec struct {
+	// Name is the identifier of the shard.
 	// +kubebuilder:validation:MaxLength=63
 	Name string `json:"name"`
 
-	// MultiOrch fully resolved spec.
+	// MultiOrch is the fully resolved configuration for the orchestrator.
 	MultiOrch MultiOrchSpec `json:"multiorch"`
 
-	// Pools fully resolved spec.
+	// Pools is the map of fully resolved data pool configurations.
 	// +kubebuilder:validation:MaxProperties=32
 	// +kubebuilder:validation:XValidation:rule="self.all(key, size(key) < 63)",message="pool names must be < 63 chars"
 	Pools map[string]PoolSpec `json:"pools"`

api/v1alpha1/toposerver_types.go

@@ -141,12 +141,17 @@ type LocalTopoServerSpec struct {
 // GlobalTopoServerRef defines a reference to the global topo server.
 // Used by Cell, TableGroup, and Shard.
 type GlobalTopoServerRef struct {
+	// Address is the DNS address of the topology server.
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=512
 	Address string `json:"address"`
+
+	// RootPath is the etcd prefix for this cluster.
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=512
 	RootPath string `json:"rootPath"`
+
+	// Implementation defines the client implementation (e.g. "etcd").
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=63
 	Implementation string `json:"implementation"`