Merge pull request #81 from numtide/api-spec-doc-comments

api: add documentation comments to exported fields

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"`