chore: improve api-doc

apis/apps/v1alpha1/clusterdefinition_types.go

@@ -1320,7 +1320,15 @@ type GVKResource struct {
 // +kubebuilder:printcolumn:name="STATUS",type="string",JSONPath=".status.phase",description="status phase"
 // +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp"
 
-// ClusterDefinition is the Schema for the ClusterDefinition API
+// ClusterDefinition defines the topology for databases or storage systems,
+// offering a variety of topological configurations to meet diverse deployment needs and scenarios.
+//
+// It includes a list of Components, each linked to a ComponentDefinition, which enhances reusability and reduce redundancy.
+// For example, widely used components such as etcd and Zookeeper can be defined once and reused across multiple ClusterDefinitions,
+// simplifying the setup of new systems.
+//
+// Additionally, ClusterDefinition also specifies the sequence of startup, upgrade, and shutdown for Components,
+// ensuring a controlled and predictable management of component lifecycles.
 type ClusterDefinition struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

apis/apps/v1alpha1/configconstraint_types.go

@@ -243,15 +243,6 @@ type ReloadOptions struct {
 	AutoTrigger *appsv1beta1.AutoTrigger `json:"autoTrigger,omitempty"`
 }
 
-// ConfigConstraint manages the parameters across multiple configuration files contained in a single configure template.
-// These configuration files should have the same format (e.g. ini, xml, properties, json).
-//
-// It provides the following functionalities:
-//
-// 1. **Parameter Value Validation**: Validates and ensures compliance of parameter values with defined constraints.
-// 2. **Dynamic Reload on Modification**: Monitors parameter changes and triggers dynamic reloads to apply updates.
-// 3. **Parameter Rendering in Templates**: Injects parameters into templates to generate up-to-date configuration files.
-//
 // +genclient
 // +genclient:nonNamespaced
 // +k8s:openapi-gen=true
@@ -260,6 +251,15 @@ type ReloadOptions struct {
 // +kubebuilder:resource:categories={kubeblocks},scope=Cluster,shortName=cc
 // +kubebuilder:printcolumn:name="PHASE",type="string",JSONPath=".status.phase",description="status phase"
 // +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp"
+
+// ConfigConstraint manages the parameters across multiple configuration files contained in a single configure template.
+// These configuration files should have the same format (e.g. ini, xml, properties, json).
+//
+// It provides the following functionalities:
+//
+// 1. **Parameter Value Validation**: Validates and ensures compliance of parameter values with defined constraints.
+// 2. **Dynamic Reload on Modification**: Monitors parameter changes and triggers dynamic reloads to apply updates.
+// 3. **Parameter Rendering in Templates**: Injects parameters into templates to generate up-to-date configuration files.
 type ConfigConstraint struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

apis/apps/v1alpha1/configuration_types.go

@@ -227,12 +227,12 @@ type ConfigurationStatus struct {
 	ConfigurationItemStatus []ConfigurationItemDetailStatus `json:"configurationStatus"`
 }
 
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+
 // Configuration represents the complete set of configurations for a specific Component of a Cluster.
 // This includes templates for each configuration file, their corresponding ConfigConstraints, volume mounts,
 // and other relevant details.
-//
-// +kubebuilder:object:root=true
-// +kubebuilder:subresource:status
 type Configuration struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

apis/apps/v1alpha1/opsrequest_types.go

@@ -163,8 +163,9 @@ type OpsRequestSpec struct {
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="forbidden to update spec.restoreFrom"
 	RestoreFrom *RestoreFromSpec `json:"restoreFrom,omitempty"`
 
-	// Specifies the maximum number of seconds the OpsRequest will wait for its start conditions to be met before aborting.
-	// If set to 0 (default), the start conditions must be met immediately for the OpsRequest to proceed.
+	// Specifies the maximum time in seconds that the OpsRequest will wait for its pre-conditions to be met
+	// before it aborts the operation.
+	// If set to 0 (default), pre-conditions must be satisfied immediately for the OpsRequest to proceed.
 	//
 	// +kubebuilder:default=0
 	// +optional
@@ -887,8 +888,13 @@ type RestoreSpec struct {
 	// +kubebuilder:default=Parallel
 	VolumeRestorePolicy string `json:"volumeRestorePolicy,omitempty"`
 
-	// If set to true, the recovery process in the PostReady phase will be performed after the cluster is running successfully.
-	// otherwise, it will be performed after component is running.
+	// Controls the timing of PostReady actions during the recovery process.
+	//
+	// If false (default), PostReady actions execute when the Component reaches the "Running" state.
+	// If true, PostReady actions are delayed until the entire Cluster is "Running,"
+	// ensuring the cluster's overall stability before proceeding.
+	//
+	// This setting is useful for coordinating PostReady operations across the Cluster for optimal cluster conditions.
 	DoReadyRestoreAfterClusterRunning bool `json:"doReadyRestoreAfterClusterRunning,omitempty"`
 }
 

apis/apps/v1alpha1/servicedescriptor_types.go

@@ -21,65 +21,84 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// ServiceDescriptorSpec defines the desired state of ServiceDescriptor
+// ServiceDescriptorSpec defines the desired state of ServiceDescriptor.
 type ServiceDescriptorSpec struct {
-	// Specifies the type or nature of the service. Should represent a well-known application cluster type, such as {mysql, redis, mongodb}.
-	// This field is case-insensitive and supports abbreviations for some well-known databases.
-	// For instance, both `zk` and `zookeeper` will be recognized as a ZooKeeper cluster, and `pg`, `postgres`, `postgresql` will all be recognized as a PostgreSQL cluster.
+	// Describes the type of database service provided by the external service.
+	// For example, "mysql", "redis", "mongodb".
+	// This field categorizes databases by their functionality, protocol and compatibility, facilitating appropriate
+	// service integration based on their unique capabilities.
+	//
+	// This field is case-insensitive.
+	//
+	// It also supports abbreviations for some well-known databases:
+	// - "pg", "pgsql", "postgres", "postgresql": PostgreSQL service
+	// - "zk", "zookeeper": ZooKeeper service
+	// - "es", "elasticsearch": Elasticsearch service
+	// - "mongo", "mongodb": MongoDB service
+	// - "ch", "clickhouse": ClickHouse service
 	//
 	// +kubebuilder:validation:Required
 	ServiceKind string `json:"serviceKind"`
 
-	// Represents the version of the service reference.
+	// Describes the version of the service provided by the external service.
+	// This is crucial for ensuring compatibility between different components of the system,
+	// as different versions of a service may have varying features.
 	//
 	// +kubebuilder:validation:Required
 	ServiceVersion string `json:"serviceVersion"`
 
-	// Represents the endpoint of the service connection credential.
+	// Specifies the URL or IP address of the external service.
 	//
 	// +optional
 	Endpoint *CredentialVar `json:"endpoint,omitempty"`
 
-	// Represents the authentication details of the service connection credential.
+	// Specifies the authentication credentials required for accessing an external service.
 	//
 	// +optional
 	Auth *ConnectionCredentialAuth `json:"auth,omitempty"`
 
-	// Represents the port of the service connection credential.
+	// Specifies the port of the external service.
 	//
 	// +optional
 	Port *CredentialVar `json:"port,omitempty" protobuf:"bytes,4,opt,name=port"`
 }
 
-// ConnectionCredentialAuth represents the authentication details of the service connection credential.
+// ConnectionCredentialAuth specifies the authentication credentials required for accessing an external service.
 type ConnectionCredentialAuth struct {
-	// Represents the username credential for the service connection.
+	// Specifies the username for the external service.
 	//
 	// +optional
 	Username *CredentialVar `json:"username,omitempty"`
 
-	// Represents the password credential for the service connection.
+	// Specifies the password for the external service.
 	//
 	// +optional
 	Password *CredentialVar `json:"password,omitempty"`
 }
 
-// CredentialVar defines the value of credential variable.
+// CredentialVar represents a variable that retrieves its value either directly from a specified expression
+// or from a source defined in `valueFrom`.
+// Only one of these options may be used at a time.
 type CredentialVar struct {
-	// Specifies an optional variable. Only one of the following may be specified.
-	// Variable references, denoted by $(VAR_NAME), are expanded using previously defined
-	// environment variables in the container and any service environment variables.
-	// If a variable cannot be resolved, the reference in the input string remains unchanged.
+	// Holds a direct string or an expression that can be evaluated to a string.
+	//
+	// It can include variables denoted by $(VAR_NAME).
+	// These variables are expanded to the value of the environment variables defined in the container.
+	// If a variable cannot be resolved, it remains unchanged in the output.
+	//
+	// To escape variable expansion and retain the literal value, use double $ characters.
+	//
+	// For example:
+	//
+	// - "$(VAR_NAME)" will be expanded to the value of the environment variable VAR_NAME.
+	// - "$$(VAR_NAME)" will result in "$(VAR_NAME)" in the output, without any variable expansion.
 	//
-	// Double $$ are reduced to a single $, enabling the escaping of the $(VAR_NAME) syntax.
-	// For instance, "$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
-	// Escaped references will never be expanded, irrespective of the variable's existence.
-	// The default value is "".
+	// Default value is an empty string.
 	//
 	// +optional
 	Value string `json:"value,omitempty" protobuf:"bytes,2,opt,name=value"`
 
-	// Defines the source for the environment variable's value. This cannot be used if the value is not empty.
+	// Specifies the source for the variable's value.
 	//
 	// +optional
 	ValueFrom *corev1.EnvVarSource `json:"valueFrom,omitempty" protobuf:"bytes,3,opt,name=valueFrom"`
@@ -117,7 +136,10 @@ func (r ServiceDescriptorStatus) GetTerminalPhases() []Phase {
 // +kubebuilder:printcolumn:name="STATUS",type="string",JSONPath=".status.phase",description="status phase"
 // +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp"
 
-// ServiceDescriptor is the Schema for the servicedescriptors API
+// ServiceDescriptor describes a service provided by external sources.
+// It contains the necessary details such as the service's address and connection credentials.
+// To enable a Cluster to access this service, the ServiceDescriptor's name should be specified
+// in the Cluster configuration under `clusterComponent.serviceRefs[*].serviceDescriptor`.
 type ServiceDescriptor struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -128,7 +150,7 @@ type ServiceDescriptor struct {
 
 // +kubebuilder:object:root=true
 
-// ServiceDescriptorList contains a list of ServiceDescriptor
+// ServiceDescriptorList contains a list of ServiceDescriptor.
 type ServiceDescriptorList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

apis/apps/v1alpha1/type.go

@@ -155,7 +155,6 @@ type ComponentConfigSpec struct {
 	// +optional
 	ConfigConstraintRef string `json:"constraintRef,omitempty"`
 
-	// Deprecated: AsEnvFrom has been deprecated since 0.9.0 and will be removed in 0.10.0
 	// Specifies the containers to inject the ConfigMap parameters as environment variables.
 	//
 	// This is useful when application images accept parameters through environment variables and
@@ -165,7 +164,8 @@ type ComponentConfigSpec struct {
 	// variables converted from the ConfigMap into these designated containers. This provides a flexible way to
 	// pass the configuration items from the ConfigMap to the container without modifying the image.
 	//
-	// Note: The field name `asEnvFrom` may be changed to `injectEnvTo` in future versions for better clarity.
+	// Deprecated: `asEnvFrom` has been deprecated since 0.9.0 and will be removed in 0.10.0.
+	// Use `injectEnvTo` instead.
 	//
 	// +kubebuilder:deprecatedversion:warning="This field has been deprecated since 0.9.0 and will be removed in 0.10.0"
 	// +listType=set
@@ -814,7 +814,7 @@ type HostNetwork struct {
 }
 
 type HostNetworkContainerPort struct {
-	// Container specifies the target container within the pod.
+	// Container specifies the target container within the Pod.
 	//
 	// +required
 	Container string `json:"container"`
@@ -1170,7 +1170,7 @@ type ComponentVars struct {
 	InstanceNames *VarOption `json:"instanceNames,omitempty"`
 }
 
-// ClusterObjectReference defines information to let you locate the referenced object inside the same cluster.
+// ClusterObjectReference defines information to let you locate the referenced object inside the same Cluster.
 type ClusterObjectReference struct {
 	// CompDef specifies the definition used by the component that the referent object resident in.
 	// If not specified, the component itself will be used.