refactor: improve comments in ModuleTemplate and Workspace API types for clarity

- Enhanced comments in ModuleTemplateStatus and WorkspaceSpec to provide clearer descriptions of fields and their purposes.
- Updated terminology in comments to ensure consistency and better understanding of the API structure.

Author: iasthc

addons/v1alpha1/moduletemplate_types.go

@@ -68,13 +68,15 @@ type ModuleTemplateSpec struct {
 	Kustomization *KustomizationTemplateSpec `json:"kustomization,omitempty"`
 }
 
-// ModuleTemplateStatus defines the observed state of the ModuleTemplate.
+// ModuleTemplateStatus defines the observed state of a ModuleTemplate.
+// It tracks whether the template has been validated and is ready for use.
 type ModuleTemplateStatus struct {
 	// ObservedGeneration is the most recent generation observed by the controller.
+	// It corresponds to the ModuleTemplate's generation, which is updated on mutation by the API Server.
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
-	// Conditions store the status conditions of the ModuleTemplate.
+	// Conditions store the status conditions of the ModuleTemplate (e.g., Ready).
 	// +listType=map
 	// +listMapKey=type
 	// +optional
@@ -99,7 +101,7 @@ type ModuleTemplate struct {
 	// +optional
 	metav1.ObjectMeta `json:"metadata,omitzero"`
 
-	// Spec defines the module template blueprint.
+	// Spec defines the desired behavior of the ModuleTemplate.
 	// +required
 	Spec ModuleTemplateSpec `json:"spec"`
 

tenant/v1alpha1/workspace_types.go

@@ -97,13 +97,13 @@ type WorkspaceSpec struct {
 	// +required
 	Members []WorkspaceMember `json:"members"`
 
-	// ResourceQuota describes the compute resource constraints (CPU, Memory, etc.) applied to the underlying namespace.
+	// ResourceQuota defines the compute resource constraints (CPU, Memory, etc.) applied to the underlying namespace.
 	// The actual schema is composed at runtime by the Schema RPC from the core/v1 ResourceQuota.
 	// +kubebuilder:pruning:PreserveUnknownFields
 	// +optional
 	ResourceQuota *runtime.RawExtension `json:"resourceQuota,omitempty"`
 
-	// LimitRange describes the default resource limits and requests for pods in the workspace.
+	// LimitRange defines the default resource limits and requests for pods in the workspace.
 	// The actual schema is composed at runtime by the Schema RPC from the core/v1 LimitRange.
 	// +kubebuilder:pruning:PreserveUnknownFields
 	// +optional
@@ -115,8 +115,6 @@ type WorkspaceSpec struct {
 }
 
 // ResourceReference is a lightweight reference to a Kubernetes resource managed by the operator.
-// Unlike corev1.ObjectReference, it only contains the essential fields needed
-// to identify the resource, avoiding stale UID/ResourceVersion issues.
 type ResourceReference struct {
 	// Name is the name of the referenced resource.
 	// +required