docs: add function documentation comments across codebase test and controller files

Author: gitcommitankit

api/v1alpha1/agentdeployment_types.go

@@ -234,6 +234,7 @@ type AgentDeploymentList struct {
 	Items           []AgentDeployment `json:"items"`
 }
 
+// init registers AgentDeployment and AgentDeploymentList types with the SchemeBuilder.
 func init() {
 	SchemeBuilder.Register(&AgentDeployment{}, &AgentDeploymentList{})
 }

api/v1alpha1/error_rate_test.go

@@ -22,6 +22,7 @@ import (
 	agentraxv1alpha1 "github.com/gitcommitankit/agentrax/api/v1alpha1"
 )
 
+// TestParseErrorRate verifies percentage string parsing across valid, invalid, and boundary inputs.
 func TestParseErrorRate(t *testing.T) {
 	t.Parallel()
 	tests := []struct {
@@ -62,6 +63,7 @@ func TestParseErrorRate(t *testing.T) {
 	}
 }
 
+// abs returns the absolute value of a float64.
 func abs(f float64) float64 {
 	if f < 0 {
 		return -f

api/v1alpha1/tenantquota_types.go

@@ -86,6 +86,7 @@ type TenantQuotaList struct {
 	Items           []TenantQuota `json:"items"`
 }
 
+// init registers TenantQuota and TenantQuotaList types with the SchemeBuilder.
 func init() {
 	SchemeBuilder.Register(&TenantQuota{}, &TenantQuotaList{})
 }

cmd/main.go

@@ -52,6 +52,7 @@ var (
 	setupLog = ctrl.Log.WithName("setup")
 )
 
+// init registers all Kubernetes core, CRD, and monitoring schemes.
 func init() {
 	utilruntime.Must(clientgoscheme.AddToScheme(scheme))
 	utilruntime.Must(autoscalingv2.AddToScheme(scheme))
@@ -62,6 +63,7 @@ func init() {
 	// +kubebuilder:scaffold:scheme
 }
 
+// main is the entrypoint for the Agentrax controller manager binary.
 func main() {
 	var metricsAddr string
 	var enableLeaderElection bool

internal/controller/agentdeployment_builder_test.go

@@ -62,6 +62,7 @@ func makeAD(name, image string, port int32, minReplicas int32) *agentraxv1alpha1
 
 // ── desiredDeployment ─────────────────────────────────────────────────────────
 
+// TestDesiredDeployment_Image verifies that the desired Deployment container image matches spec.image.
 func TestDesiredDeployment_Image(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD("my-agent", "registry.io/agent:v1", 8080, 1)
@@ -72,6 +73,7 @@ func TestDesiredDeployment_Image(t *testing.T) {
 	}
 }
 
+// TestDesiredDeployment_Port verifies container port configuration and default fallback.
 func TestDesiredDeployment_Port(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -94,6 +96,7 @@ func TestDesiredDeployment_Port(t *testing.T) {
 	}
 }
 
+// TestDesiredDeployment_Replicas verifies that desired Deployment replicas match spec.replicas.min.
 func TestDesiredDeployment_Replicas(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testDefaultAgent, testDefaultImage, 8080, 3)
@@ -104,6 +107,7 @@ func TestDesiredDeployment_Replicas(t *testing.T) {
 	}
 }
 
+// TestDesiredDeployment_EnvAndArgs verifies propagation of environment variables and container arguments.
 func TestDesiredDeployment_EnvAndArgs(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testDefaultAgent, testDefaultImage, 8080, 1)
@@ -121,6 +125,7 @@ func TestDesiredDeployment_EnvAndArgs(t *testing.T) {
 	}
 }
 
+// TestDesiredDeployment_Resources verifies container CPU and Memory resource requests/limits propagation.
 func TestDesiredDeployment_Resources(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testDefaultAgent, testDefaultImage, 8080, 1)
@@ -153,6 +158,7 @@ func TestDesiredDeployment_Resources(t *testing.T) {
 	}
 }
 
+// TestDesiredDeployment_Labels verifies required standard labels on Deployment and Pod template.
 func TestDesiredDeployment_Labels(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testAgentName, testDefaultImage, 8080, 1)
@@ -173,6 +179,7 @@ func TestDesiredDeployment_Labels(t *testing.T) {
 	}
 }
 
+// TestDesiredDeployment_SelectorMatchesPodLabels verifies Deployment selector matches Pod template labels.
 func TestDesiredDeployment_SelectorMatchesPodLabels(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testDefaultAgent, testDefaultImage, 8080, 1)
@@ -187,6 +194,7 @@ func TestDesiredDeployment_SelectorMatchesPodLabels(t *testing.T) {
 
 // ── desiredService ────────────────────────────────────────────────────────────
 
+// TestDesiredService_Port verifies Service port configuration and default fallback.
 func TestDesiredService_Port(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -208,6 +216,7 @@ func TestDesiredService_Port(t *testing.T) {
 	}
 }
 
+// TestDesiredService_Selector verifies Service selector targets the agent pod label.
 func TestDesiredService_Selector(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testAgentName, testDefaultImage, 8080, 1)
@@ -218,6 +227,7 @@ func TestDesiredService_Selector(t *testing.T) {
 	}
 }
 
+// TestDesiredService_ClusterIPType verifies that the created Service is of type ClusterIP.
 func TestDesiredService_ClusterIPType(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testDefaultAgent, testDefaultImage, 8080, 1)
@@ -230,6 +240,7 @@ func TestDesiredService_ClusterIPType(t *testing.T) {
 
 // ── agentLabels ───────────────────────────────────────────────────────────────
 
+// TestAgentLabels verifies standard label generation for an AgentDeployment.
 func TestAgentLabels(t *testing.T) {
 	ad := &agentraxv1alpha1.AgentDeployment{
 		ObjectMeta: metav1.ObjectMeta{Name: "foo"},
@@ -251,6 +262,7 @@ func TestAgentLabels(t *testing.T) {
 
 // ── condition helpers ─────────────────────────────────────────────────────────
 
+// TestSetAndGetCondition verifies setting and reading status conditions on AgentDeployment.
 func TestSetAndGetCondition(t *testing.T) {
 	ad := &agentraxv1alpha1.AgentDeployment{}
 
@@ -268,6 +280,7 @@ func TestSetAndGetCondition(t *testing.T) {
 	}
 }
 
+// TestSetCondition_Overwrite verifies that updating an existing condition updates in-place without duplicates.
 func TestSetCondition_Overwrite(t *testing.T) {
 	ad := &agentraxv1alpha1.AgentDeployment{}
 
@@ -284,6 +297,7 @@ func TestSetCondition_Overwrite(t *testing.T) {
 	}
 }
 
+// TestRemoveCondition verifies condition removal from the status condition slice.
 func TestRemoveCondition(t *testing.T) {
 	ad := &agentraxv1alpha1.AgentDeployment{}
 
@@ -300,6 +314,7 @@ func TestRemoveCondition(t *testing.T) {
 	}
 }
 
+// TestRemoveCondition_NonExistent verifies that removing a non-existent condition is a safe no-op.
 func TestRemoveCondition_NonExistent(t *testing.T) {
 	ad := &agentraxv1alpha1.AgentDeployment{}
 	// Should be a no-op, not panic.
@@ -309,6 +324,7 @@ func TestRemoveCondition_NonExistent(t *testing.T) {
 	}
 }
 
+// TestGetCondition_Absent verifies that querying an un-set condition returns nil.
 func TestGetCondition_Absent(t *testing.T) {
 	ad := &agentraxv1alpha1.AgentDeployment{}
 	c := GetCondition(ad, agentraxv1alpha1.ConditionReady)
@@ -319,6 +335,7 @@ func TestGetCondition_Absent(t *testing.T) {
 
 // ── desiredServiceMonitor ─────────────────────────────────────────────────────
 
+// TestDesiredServiceMonitor_Endpoint verifies ServiceMonitor metrics endpoint configuration.
 func TestDesiredServiceMonitor_Endpoint(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testDefaultAgent, testDefaultImage, 8080, 1)
@@ -336,6 +353,7 @@ func TestDesiredServiceMonitor_Endpoint(t *testing.T) {
 	}
 }
 
+// TestDesiredServiceMonitor_SelectorMatchesLabels verifies ServiceMonitor selector matches agent labels.
 func TestDesiredServiceMonitor_SelectorMatchesLabels(t *testing.T) {
 	r := &AgentDeploymentReconciler{}
 	ad := makeAD(testAgentName, testDefaultImage, 8080, 1)

internal/controller/suite_test.go

@@ -67,6 +67,7 @@ var testReconciler *AgentDeploymentReconciler
 // and the validating webhook in integration tests.
 var testEnforcer *quota.Enforcer
 
+// TestControllers is the Ginkgo test suite runner for controller integration tests.
 func TestControllers(t *testing.T) {
 	RegisterFailHandler(Fail)
 	RunSpecs(t, "Controller Suite")

internal/controller/tenantquota_controller_test.go

@@ -350,6 +350,7 @@ var _ = Describe("TenantQuota Controller", func() {
 
 // ── Test helpers ──────────────────────────────────────────────────────────────
 
+// makeTQ creates a TenantQuota object with the provided limits for test fixtures.
 func makeTQ(name, ns string, maxAgents, maxGPUs, maxTotalReplicas, maxReplicasPerAgent int32) *agentraxv1alpha1.TenantQuota { //nolint:unparam
 	return &agentraxv1alpha1.TenantQuota{
 		ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: ns},

internal/quota/enforcer_test.go

@@ -35,6 +35,7 @@ import (
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
+// makeSpec creates an AgentDeploymentSpec test fixture with given maxReplicas and GPU limit.
 func makeSpec(maxReplicas int32, gpuLimit string) agentraxv1alpha1.AgentDeploymentSpec {
 	spec := agentraxv1alpha1.AgentDeploymentSpec{
 		Image:     "test-image:v1",
@@ -56,6 +57,7 @@ func makeSpec(maxReplicas int32, gpuLimit string) agentraxv1alpha1.AgentDeployme
 	return spec
 }
 
+// makeQuota creates a TenantQuotaSpec test fixture with given quota limits.
 func makeQuota(maxAgents, maxGPUs, maxTotalReplicas, maxReplicasPerAgent int32) agentraxv1alpha1.TenantQuotaSpec {
 	return agentraxv1alpha1.TenantQuotaSpec{
 		MaxAgents:           maxAgents,
@@ -65,6 +67,7 @@ func makeQuota(maxAgents, maxGPUs, maxTotalReplicas, maxReplicasPerAgent int32)
 	}
 }
 
+// makeUsage creates a TenantQuotaStatus test fixture with given observed usage.
 func makeUsage(agents, gpus, replicas int32) agentraxv1alpha1.TenantQuotaStatus {
 	return agentraxv1alpha1.TenantQuotaStatus{
 		UsedAgents:        agents,
@@ -84,6 +87,7 @@ func newTestEnforcer(t *testing.T) *Enforcer {
 
 // ── canAdmit tests ────────────────────────────────────────────────────────────
 
+// TestCanAdmit_Create verifies admission decisions for new AgentDeployment creates against various quota scenarios.
 func TestCanAdmit_Create(t *testing.T) {
 	t.Parallel()
 	tests := []struct {
@@ -170,6 +174,7 @@ func TestCanAdmit_Create(t *testing.T) {
 	}
 }
 
+// TestCanAdmit_Update verifies admission decisions when updating existing AgentDeployment specs.
 func TestCanAdmit_Update(t *testing.T) {
 	t.Parallel()
 	e := newTestEnforcer(t)
@@ -197,6 +202,7 @@ func TestCanAdmit_Update(t *testing.T) {
 	}
 }
 
+// TestCanAdmit_Update_MaxReplicasPerAgent_Downgrade verifies that lowering maxReplicasPerAgent does not deadlock updates that do not increase replicas.
 func TestCanAdmit_Update_MaxReplicasPerAgent_Downgrade(t *testing.T) {
 	// When maxReplicasPerAgent is lowered below an existing AD's replicas.max,
 	// updates that do NOT further increase replicas.max must still be allowed.
@@ -235,6 +241,7 @@ func TestCanAdmit_Update_MaxReplicasPerAgent_Downgrade(t *testing.T) {
 
 // ── In-flight reservation tests ───────────────────────────────────────────────
 
+// TestReservation_BlocksConcurrentCreate verifies that an in-flight reservation blocks concurrent creation of the same remaining slot.
 func TestReservation_BlocksConcurrentCreate(t *testing.T) {
 	t.Parallel()
 	e := newTestEnforcer(t)
@@ -265,6 +272,7 @@ func TestReservation_BlocksConcurrentCreate(t *testing.T) {
 	}
 }
 
+// TestReservation_DoesNotDoubleCount verifies that re-admission for the same AD key excludes its own prior reservation.
 func TestReservation_DoesNotDoubleCount(t *testing.T) {
 	// A re-admission for the same AD key should exclude its own prior reservation
 	// so it isn't double-counted.
@@ -398,6 +406,7 @@ func TestAdmitAndReserve_AtomicRaceProtection(t *testing.T) {
 
 // ── ComputeUsage tests ────────────────────────────────────────────────────────
 
+// TestComputeUsage verifies aggregation of agents, GPUs, and replicas across multiple AgentDeployment specs.
 func TestComputeUsage(t *testing.T) {
 	t.Parallel()
 	e := newTestEnforcer(t)
@@ -418,6 +427,7 @@ func TestComputeUsage(t *testing.T) {
 	}
 }
 
+// TestComputeUsage_Empty verifies that empty input returns all-zero usage.
 func TestComputeUsage_Empty(t *testing.T) {
 	t.Parallel()
 	e := newTestEnforcer(t)
@@ -429,6 +439,7 @@ func TestComputeUsage_Empty(t *testing.T) {
 
 // ── IsOverQuota tests ─────────────────────────────────────────────────────────
 
+// TestIsOverQuota verifies over-quota condition detection across agents, GPUs, and replicas dimensions.
 func TestIsOverQuota(t *testing.T) {
 	t.Parallel()
 	e := newTestEnforcer(t)
@@ -464,6 +475,7 @@ func TestIsOverQuota(t *testing.T) {
 // ParseErrorRate lives in api/v1alpha1 to avoid an import cycle.
 // Its tests are in api/v1alpha1/webhook_test.go.
 
+// TestParseErrorRate_ViaV1alpha1 verifies ParseErrorRate is accessible and correct from outside api/v1alpha1.
 func TestParseErrorRate_ViaV1alpha1(t *testing.T) {
 	// Smoke-test that ParseErrorRate is accessible from outside api/v1alpha1.
 	t.Parallel()
@@ -478,6 +490,7 @@ func TestParseErrorRate_ViaV1alpha1(t *testing.T) {
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
+// absFloat returns the absolute value of a float64.
 func absFloat(f float64) float64 {
 	if f < 0 {
 		return -f