chore: tidy up API docs (#6625)

Makefile

@@ -261,7 +261,7 @@ lorryctl-doc: generate test-go-generate ## generate CLI command reference manual
 
 .PHONY: api-doc
 api-doc:  ## generate API reference manual.
-	@./hack/docgen/api/generate.sh
+	$(GO) run ./hack/docgen/api/main.go -api-dir github.com/apecloud/kubeblocks/apis -config ./hack/docgen/api/gen-api-doc-config.json -template-dir ./hack/docgen/api/template -out-dir ./docs/developer_docs/api-reference/
 
 .PHONY: doc
 doc: lorryctl-doc api-doc ## generate all documents.

apis/apis.go

@@ -0,0 +1,17 @@
+/*
+Copyright (C) 2022-2024 ApeCloud Co., Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package apis

apis/apps/v1alpha1/backuppolicytemplate_types.go

@@ -136,21 +136,25 @@ type SchedulePolicy struct {
 	// controller will remove all backups that are older than the RetentionPeriod.
 	// For example, RetentionPeriod of `30d` will keep only the backups of last 30 days.
 	// Sample duration format:
+	//
 	// - years: 	2y
 	// - months: 	6mo
 	// - days: 		30d
 	// - hours: 	12h
 	// - minutes: 	30m
 	// You can also combine the above durations. For example: 30d12h30m
+	//
 	// +optional
 	// +kubebuilder:default="7d"
 	RetentionPeriod dpv1alpha1.RetentionPeriod `json:"retentionPeriod,omitempty"`
 }
 
 type TargetInstance struct {
 	// select instance of corresponding role for backup, role are:
+	//
 	// - the name of Leader/Follower/Leaner for Consensus component.
 	// - primary or secondary for Replication component.
+	//
 	// finally, invalid role of the component will be ignored.
 	// such as if workload type is Replication and component's replicas is 1,
 	// the secondary role is invalid. and it also will be ignored when component is Stateful/Stateless.
@@ -167,8 +171,10 @@ type TargetInstance struct {
 	// PodSelectionStrategy specifies the strategy to select when multiple pods are
 	// selected for backup target.
 	// Valid values are:
+	//
 	// - Any: select any one pod that match the labelsSelector.
 	// - All: select all pods that match the labelsSelector.
+	//
 	// +optional
 	Strategy dpv1alpha1.PodSelectionStrategy `json:"strategy,omitempty"`
 

apis/apps/v1alpha1/cluster_types.go

@@ -138,12 +138,15 @@ type ClusterBackup struct {
 	// controller will remove all backups that are older than the RetentionPeriod.
 	// For example, RetentionPeriod of `30d` will keep only the backups of last 30 days.
 	// Sample duration format:
+	//
 	// - years: 	2y
 	// - months: 	6mo
 	// - days: 		30d
 	// - hours: 	12h
 	// - minutes: 	30m
+	//
 	// You can also combine the above durations. For example: 30d12h30m
+	//
 	// +kubebuilder:default="7d"
 	// +optional
 	RetentionPeriod dpv1alpha1.RetentionPeriod `json:"retentionPeriod,omitempty"`
@@ -317,29 +320,29 @@ type ShardingSpec struct {
 
 // ClusterComponentSpec defines the cluster component spec.
 // +kubebuilder:validation:XValidation:rule="has(self.componentDefRef) || has(self.componentDef)",message="either componentDefRef or componentDef should be provided"
-// //(TODO) +kubebuilder:validation:XValidation:rule="!has(oldSelf.componentDefRef) || has(self.componentDefRef)", message="componentDefRef is required once set"
-// //(TODO) +kubebuilder:validation:XValidation:rule="!has(oldSelf.componentDef) || has(self.componentDef)", message="componentDef is required once set"
+// TODO +kubebuilder:validation:XValidation:rule="!has(oldSelf.componentDefRef) || has(self.componentDefRef)", message="componentDefRef is required once set"
+// TODO +kubebuilder:validation:XValidation:rule="!has(oldSelf.componentDef) || has(self.componentDef)", message="componentDef is required once set"
 type ClusterComponentSpec struct {
 	// name defines cluster's component name, this name is also part of Service DNS name, so this name will comply with IANA Service Naming rule.
 	// When ClusterComponentSpec is referenced as a template, name is optional. Otherwise, it is required.
 	// +kubebuilder:validation:MaxLength=22
 	// +kubebuilder:validation:Pattern:=`^[a-z]([a-z0-9\-]*[a-z0-9])?$`
-	// //(TODO) +kubebuilder:validation:XValidation:rule="self == oldSelf",message="name is immutable"
+	// TODO +kubebuilder:validation:XValidation:rule="self == oldSelf",message="name is immutable"
 	// +optional
 	Name string `json:"name"`
 
 	// componentDefRef references componentDef defined in ClusterDefinition spec. Need to comply with IANA Service Naming rule.
 	// +kubebuilder:validation:MaxLength=22
 	// +kubebuilder:validation:Pattern:=`^[a-z]([a-z0-9\-]*[a-z0-9])?$`
-	// //(TODO) +kubebuilder:validation:XValidation:rule="self == oldSelf",message="componentDefRef is immutable"
+	// TODO +kubebuilder:validation:XValidation:rule="self == oldSelf",message="componentDefRef is immutable"
 	// +optional
 	ComponentDefRef string `json:"componentDefRef,omitempty"`
 
 	// componentDef references the name of the ComponentDefinition.
 	// If both componentDefRef and componentDef are provided, the componentDef will take precedence over componentDefRef.
 	// +kubebuilder:validation:MaxLength=22
 	// +kubebuilder:validation:Pattern:=`^[a-z0-9]([a-z0-9\.\-]*[a-z0-9])?$`
-	// //(TODO) +kubebuilder:validation:XValidation:rule="self == oldSelf",message="componentDef is immutable"
+	// TODO +kubebuilder:validation:XValidation:rule="self == oldSelf",message="componentDef is immutable"
 	// +optional
 	ComponentDef string `json:"componentDef,omitempty"`
 
@@ -600,8 +603,10 @@ type TLSConfig struct {
 type Issuer struct {
 	// Name of issuer.
 	// Options supported:
+	//
 	// - KubeBlocks - Certificates signed by KubeBlocks Operator.
 	// - UserProvided - User provided own CA-signed certificates.
+	//
 	// +kubebuilder:validation:Enum={KubeBlocks, UserProvided}
 	// +kubebuilder:default=KubeBlocks
 	// +kubebuilder:validation:Required

apis/apps/v1alpha1/clusterdefinition_types.go

@@ -49,18 +49,20 @@ type ClusterDefinitionSpec struct {
 	// secret for cluster.apps.kubeblocks.io object.
 	//
 	// Built-in objects are:
-	// - `$(RANDOM_PASSWD)` - random 8 characters.
-	// - `$(STRONG_RANDOM_PASSWD)` - random 16 characters, with mixed cases, digits and symbols.
-	// - `$(UUID)` - generate a random UUID v4 string.
-	// - `$(UUID_B64)` - generate a random UUID v4 BASE64 encoded string.
-	// - `$(UUID_STR_B64)` - generate a random UUID v4 string then BASE64 encoded.
-	// - `$(UUID_HEX)` - generate a random UUID v4 HEX representation.
-	// - `$(HEADLESS_SVC_FQDN)` - headless service FQDN placeholder, value pattern - $(CLUSTER_NAME)-$(1ST_COMP_NAME)-headless.$(NAMESPACE).svc,
+	//
+	// - `$(RANDOM_PASSWD)` random 8 characters.
+	// dfjksgks
+	// - `$(STRONG_RANDOM_PASSWD)` random 16 characters, with mixed cases, digits and symbols.
+	// - `$(UUID)` generate a random UUID v4 string.
+	// - `$(UUID_B64)` generate a random UUID v4 BASE64 encoded string.
+	// - `$(UUID_STR_B64)` generate a random UUID v4 string then BASE64 encoded.
+	// - `$(UUID_HEX)` generate a random UUID v4 HEX representation.
+	// - `$(HEADLESS_SVC_FQDN)` headless service FQDN placeholder, value pattern is `$(CLUSTER_NAME)-$(1ST_COMP_NAME)-headless.$(NAMESPACE).svc`,
 	//    where 1ST_COMP_NAME is the 1st component that provide `ClusterDefinition.spec.componentDefs[].service` attribute;
-	// - `$(SVC_FQDN)` - service FQDN  placeholder, value pattern - $(CLUSTER_NAME)-$(1ST_COMP_NAME).$(NAMESPACE).svc,
+	// - `$(SVC_FQDN)` service FQDN placeholder, value pattern is `$(CLUSTER_NAME)-$(1ST_COMP_NAME).$(NAMESPACE).svc`,
 	//    where 1ST_COMP_NAME is the 1st component that provide `ClusterDefinition.spec.componentDefs[].service` attribute;
-	// - `$(SVC_PORT_{PORT-NAME})` - a ServicePort's port value with specified port name, i.e, a servicePort JSON struct:
-	//    `{"name": "mysql", "targetPort": "mysqlContainerPort", "port": 3306}`, and "$(SVC_PORT_mysql)" in the
+	// - `$(SVC_PORT_{PORT-NAME})` is ServicePort's port value with specified port name, i.e, a servicePort JSON struct:
+	//    `{"name": "mysql", "targetPort": "mysqlContainerPort", "port": 3306}`, and `$(SVC_PORT_mysql)` in the
 	//    connection credential value is 3306.
 	// +optional
 	ConnectionCredential map[string]string `json:"connectionCredential,omitempty"`
@@ -388,22 +390,22 @@ type ClusterComponentDefinition struct {
 
 	// statelessSpec defines stateless related spec if workloadType is Stateless.
 	// +optional
-	//+kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
+	// +kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
 	StatelessSpec *StatelessSetSpec `json:"statelessSpec,omitempty"`
 
 	// statefulSpec defines stateful related spec if workloadType is Stateful.
 	// +optional
-	//+kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
+	// +kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
 	StatefulSpec *StatefulSetSpec `json:"statefulSpec,omitempty"`
 
 	// consensusSpec defines consensus related spec if workloadType is Consensus, required if workloadType is Consensus.
 	// +optional
-	//+kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
+	// +kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
 	ConsensusSpec *ConsensusSetSpec `json:"consensusSpec,omitempty"`
 
 	// replicationSpec defines replication related spec if workloadType is Replication.
 	// +optional
-	//+kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
+	// +kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
 	ReplicationSpec *ReplicationSetSpec `json:"replicationSpec,omitempty"`
 
 	// RSMSpec defines workload related spec of this component.
@@ -653,7 +655,7 @@ type ClusterDefinitionProbes struct {
 
 	// Probe for DB role changed check.
 	// +optional
-	//+kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
+	// +kubebuilder:deprecatedversion:warning="This field is deprecated from KB 0.7.0, use RSMSpec instead."
 	RoleProbe *ClusterDefinitionProbe `json:"roleProbe,omitempty"`
 
 	// roleProbeTimeoutAfterPodsReady(in seconds), when all pods of the component are ready,

apis/apps/v1alpha1/componentdefinition_types.go

@@ -45,7 +45,7 @@ type ComponentDefinition struct {
 	Status ComponentDefinitionStatus `json:"status,omitempty"`
 }
 
-//+kubebuilder:object:root=true
+// +kubebuilder:object:root=true
 
 // ComponentDefinitionList contains a list of ComponentDefinition
 type ComponentDefinitionList struct {
@@ -482,13 +482,15 @@ type Action struct {
 	RetryPolicy *RetryPolicy `json:"retryPolicy,omitempty"`
 
 	// PreCondition defines the condition when the action will be executed.
+	//
 	// - Immediately: The Action is executed immediately after the Component object is created,
-	// without guaranteeing the availability of the Component and its underlying resources. only after the action is successfully executed will the Component's state turn to ready.
+	//   without guaranteeing the availability of the Component and its underlying resources. only after the action is successfully executed will the Component's state turn to ready.
 	// - RuntimeReady: The Action is executed after the Component object is created and once all underlying Runtimes are ready.
-	// only after the action is successfully executed will the Component's state turn to ready.
+	//   only after the action is successfully executed will the Component's state turn to ready.
 	// - ComponentReady: The Action is executed after the Component object is created and once the Component is ready.
-	// the execution process does not impact the state of the Component and the Cluster.
+	//   the execution process does not impact the state of the Component and the Cluster.
 	// - ClusterReady: The Action is executed after the Cluster object is created and once the Cluster is ready.
+	//
 	// the execution process does not impact the state of the Component and the Cluster.
 	// Cannot be updated.
 	// +optional
@@ -531,12 +533,15 @@ type ComponentLifecycleActions struct {
 	// You can define the preCondition for executing PostProvision using Action.PreCondition. The default PostProvision action preCondition is ComponentReady.
 	// The PostProvision Action will be executed only once.
 	// Dedicated env vars for the action:
+	//
 	// - KB_CLUSTER_COMPONENT_LIST: The list of all components in the cluster, joined by ',' (e.g., "comp1,comp2").
 	// - KB_CLUSTER_COMPONENT_POD_NAME_LIST: The list of all pods name in this component, joined by ',' (e.g., "pod1,pod2").
 	// - KB_CLUSTER_COMPONENT_POD_IP_LIST: The list of pod IPs where each pod resides in this component, corresponding one-to-one with each pod in the KB_CLUSTER_COMPONENT_POD_NAME_LIST. joined by ',' (e.g., "podIp1,podIp2").
 	// - KB_CLUSTER_COMPONENT_POD_HOST_NAME_LIST: The list of hostName where each pod resides in this component, corresponding one-to-one with each pod in the KB_CLUSTER_COMPONENT_POD_NAME_LIST. joined by ',' (e.g., "hostName1,hostName2").
 	// - KB_CLUSTER_COMPONENT_POD_HOST_IP_LIST: The list of host IPs where each pod resides in this component, corresponding one-to-one with each pod in the KB_CLUSTER_COMPONENT_POD_NAME_LIST. joined by ',' (e.g., "hostIp1,hostIp2").
+	//
 	// Cannot be updated.
+	//
 	// +optional
 	PostProvision *LifecycleActionHandler `json:"postProvision,omitempty"`
 
@@ -554,20 +559,27 @@ type ComponentLifecycleActions struct {
 
 	// Switchover defines how to proactively switch the current leader to a new replica to minimize the impact on availability.
 	// This action is typically invoked when the leader is about to become unavailable due to events, such as:
+	//
 	// - switchover
 	// - stop
 	// - restart
 	// - scale-in
+	//
 	// Dedicated env vars for the action:
+	//
 	// - KB_SWITCHOVER_CANDIDATE_NAME: The name of the new candidate replica's Pod. It may be empty.
 	// - KB_SWITCHOVER_CANDIDATE_FQDN: The FQDN of the new candidate replica. It may be empty.
 	// - KB_LEADER_POD_IP: The IP address of the original leader's Pod before switchover.
 	// - KB_LEADER_POD_NAME: The name of the original leader's Pod before switchover.
 	// - KB_LEADER_POD_FQDN: The FQDN of the original leader's Pod before switchover.
+	//
 	// The env vars with following prefix are deprecated and will be removed in the future:
+	//
 	// - KB_REPLICATION_PRIMARY_POD_: The prefix of the environment variables of the original primary's Pod before switchover.
 	// - KB_CONSENSUS_LEADER_POD_: The prefix of the environment variables of the original leader's Pod before switchover.
+	//
 	// Cannot be updated.
+	//
 	// +optional
 	Switchover *ComponentSwitchover `json:"switchover,omitempty"`
 
@@ -599,11 +611,14 @@ type ComponentLifecycleActions struct {
 
 	// DataPopulate defines how to populate the data to create new replicas.
 	// This action is typically used when a new replica needs to be constructed, such as:
+	//
 	// - scale-out
 	// - rebuild
 	// - clone
+	//
 	// It should write the valid data to stdout without including any extraneous information.
 	// Cannot be updated.
+	//
 	// +optional
 	DataPopulate *LifecycleActionHandler `json:"dataPopulate,omitempty"`
 

apis/apps/v1alpha1/doc.go

@@ -17,8 +17,6 @@ You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/developer_docs/api-reference/cluster.md
-
 // +k8s:deepcopy-gen=package,register
 // +k8s:openapi-gen=true
 // +groupName=apps.kubeblocks.io

apis/apps/v1alpha1/opsdefinition_types.go

@@ -83,10 +83,12 @@ type ComponentDefinitionRef struct {
 type ParametersSchema struct {
 	// openAPIV3Schema is the OpenAPI v3 schema to use for parameter schema.
 	// supported properties types:
+	//
 	// - string
 	// - number
 	// - integer
 	// - array: only supported the item with string type.
+	//
 	// +kubebuilder:validation:Schemaless
 	// +kubebuilder:validation:Type=object
 	// +kubebuilder:pruning:PreserveUnknownFields
@@ -97,8 +99,10 @@ type ParametersSchema struct {
 
 type VarsRef struct {
 	// podSelectionStrategy how to select the target component pod for variable references based on the strategy.
+	//
 	// - PreferredAvailable: prioritize the selection of available pod.
 	// - Available: only select available pod. if not found, terminating the operation.
+	//
 	// +kubebuilder:validation:Required
 	// +kubebuilder:default=PreferredAvailable
 	PodSelectionStrategy PodSelectionStrategy `json:"podSelectionStrategy"`
@@ -152,9 +156,11 @@ type PreCondition struct {
 type Rule struct {
 	// expression declares how the operation can be executed using go template expression.
 	// it should return "true" or "false", built-in objects:
+	//
 	// - "params" are input parameters.
 	// - "cluster" is referenced cluster object.
 	// - "component" is referenced the component Object.
+	//
 	// +kubebuilder:validation:Required
 	Expression string `json:"expression"`
 

apis/apps/v1alpha1/opsrequest_types.go

@@ -518,13 +518,16 @@ type BackupSpec struct {
 	// Controller will remove all backups that are older than the RetentionPeriod.
 	// For example, RetentionPeriod of `30d` will keep only the backups of last 30 days.
 	// Sample duration format:
+	//
 	// - years: 	2y
 	// - months: 	6mo
 	// - days: 		30d
 	// - hours: 	12h
 	// - minutes: 	30m
+	//
 	// You can also combine the above durations. For example: 30d12h30m.
 	// If not set, the backup will be kept forever.
+	//
 	// +optional
 	RetentionPeriod string `json:"retentionPeriod,omitempty"`
 

apis/dataprotection/v1alpha1/backup_types.go

@@ -51,13 +51,16 @@ type BackupSpec struct {
 	// Controller will remove all backups that are older than the RetentionPeriod.
 	// For example, RetentionPeriod of `30d` will keep only the backups of last 30 days.
 	// Sample duration format:
+	//
 	// - years: 	2y
 	// - months: 	6mo
 	// - days: 		30d
 	// - hours: 	12h
 	// - minutes: 	30m
+	//
 	// You can also combine the above durations. For example: 30d12h30m.
 	// If not set, the backup will be kept forever.
+	//
 	// +optional
 	RetentionPeriod RetentionPeriod `json:"retentionPeriod,omitempty"`
 

apis/dataprotection/v1alpha1/backuppolicy_types.go

@@ -88,8 +88,10 @@ type PodSelector struct {
 	// strategy specifies the strategy to select the target pod when multiple pods
 	// are selected.
 	// Valid values are:
+	//
 	// - Any: select any one pod that match the labelsSelector.
 	// - All: select all pods that match the labelsSelector.
+	//
 	// +kubebuilder:default=Any
 	Strategy PodSelectionStrategy `json:"strategy,omitempty"`
 }

apis/dataprotection/v1alpha1/backupschedule_types.go

@@ -58,12 +58,15 @@ type SchedulePolicy struct {
 	// controller will remove all backups that are older than the RetentionPeriod.
 	// For example, RetentionPeriod of `30d` will keep only the backups of last 30 days.
 	// Sample duration format:
+	//
 	// - years: 	2y
 	// - months: 	6mo
 	// - days: 		30d
 	// - hours: 	12h
 	// - minutes: 	30m
+	//
 	// You can also combine the above durations. For example: 30d12h30m
+	//
 	// +optional
 	// +kubebuilder:default="7d"
 	RetentionPeriod RetentionPeriod `json:"retentionPeriod,omitempty"`

apis/dataprotection/v1alpha1/doc.go

@@ -17,8 +17,6 @@ You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-//go:generate go run ../../../hack/docgen/api/main.go -api-dir . -config ../../../hack/docgen/api/gen-api-doc-config.json -template-dir ../../../hack/docgen/api/template -out-file ../../../docs/developer_docs/api-reference/backup.md
-
 // +k8s:deepcopy-gen=package,register
 // +k8s:openapi-gen=true
 // +groupName=dataprotection.kubeblocks.io