Add docs for CRDs

src/go/k8s/api/cluster.redpanda.com/v1alpha1/events_topic.go

@@ -1,21 +1,21 @@
 package v1alpha1
 
-// These constants define valid event severity values.
+// Defines valid event severity values.
 const (
-	// EventTopicCreationFailure indicate and error when topic creation
+	// Indicate an error when topic creation
 	// was not successful.
 	EventTopicCreationFailure string = "topicCreationFailure"
-	// EventTopicDeletionFailure indicate and error when topic deletion
+	// Indicates an error when topic deletion
 	// was not successful.
 	EventTopicDeletionFailure string = "topicDeletionFailure"
-	// EventTopicConfigurationAlteringFailure indicate and error when topic configuration altering
+	// Indicates an error when topic configuration altering
 	// was not successful.
 	EventTopicConfigurationAlteringFailure string = "topicConfigurationAlteringFailure"
-	// EventTopicConfigurationDescribeFailure indicate and error when topic configuration describe
+	// Indicates an error when topic configuration describe
 	// was not successful.
 	EventTopicConfigurationDescribeFailure string = "topicConfigurationDescribeFailure"
-	// EventTopicAlreadySynced indicate topic is already synced
+	// Indicates that the topic is already synced.
 	EventTopicAlreadySynced string = "topicAlreadySynced"
-	// EventTopicSynced indicate topic is synced
+	// Indicates that a topic is synced.
 	EventTopicSynced string = "topicSynced"
 )

src/go/k8s/api/cluster.redpanda.com/v1alpha1/topic_types.go

@@ -20,8 +20,8 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
-// SecretKeyRef contains enough information to inspect or modify the referred Secret data
-// REF https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference
+// Contains enough information to inspect or modify the referred Secret data
+// See https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference.
 type SecretKeyRef struct {
 	// Name of the referent.
 	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
@@ -32,7 +32,7 @@ type SecretKeyRef struct {
 	Key string `json:"key,omitempty"`
 }
 
-// GetValue retrieve the value from corev1.Secret{}
+// Retrieves the value from `corev1.Secret{}`.
 func (s *SecretKeyRef) GetValue(
 	ctx context.Context, cl client.Client, namespace, defaultKey string,
 ) ([]byte, error) {
@@ -64,65 +64,70 @@ func (s *SecretKeyRef) getValue(
 	return value, nil
 }
 
-// TopicSpec defines the desired state of Topic
+// Defines the desired state of the topic.
 type TopicSpec struct {
-	// Partitions is the number topic shards that is distributed across the nodes in a cluster.
-	// This cannot be decreased after topic creation.
+	// Specifies the number of topic shards that are distributed across the brokers in a cluster.
+	// This number cannot be decreased after topic creation.
 	// It can be increased after topic creation, but it is
 	// important to understand the consequences that has, especially for
 	// topics with semantic partitioning. When absent this will default to
 	// the Redpanda cluster configuration `default_topic_partitions`.
-	// https://docs.redpanda.com/docs/reference/cluster-properties/#default_topic_partitions
+	// See https://docs.redpanda.com/docs/reference/cluster-properties/#default_topic_partitions and
 	// https://docs.redpanda.com/docs/get-started/architecture/#partitions
 	Partitions *int `json:"partitions,omitempty"`
-	// ReplicationFactor is the number of replicas the topic should have. Must be odd value.
+	// Specifies the number of replicas the topic should have. Must be odd value.
 	// When absent this will default to the Redpanda cluster configuration `default_topic_replications`.
-	// https://docs.redpanda.com/docs/reference/cluster-properties/#default_topic_replications
+	// See https://docs.redpanda.com/docs/reference/cluster-properties/#default_topic_replications.
 	ReplicationFactor *int `json:"replicationFactor,omitempty"`
-	// OverwriteTopicName will change the topic name from the `metadata.name` to `OverwriteTopicName`
+	// Changes the topic name from the value of `metadata.name`.
 	OverwriteTopicName *string `json:"overwriteTopicName,omitempty"`
-	// AdditionalConfig is free form map of any configuration option that topic can have.
+	// Adds extra topic configurations. This is a free-form map of any configuration options that topics can have.
 	// Examples:
-	// cleanup.policy=compact
-	// redpanda.remote.write=true
-	// redpanda.remote.read=true
-	// redpanda.remote.recovery=true
-	// redpanda.remote.delete=true
+	// `cleanup.policy=compact`
+	// `redpanda.remote.write=true`
+	// `redpanda.remote.read=true`
+	// `redpanda.remote.recovery=true`
+	// `redpanda.remote.delete=true`
 	AdditionalConfig map[string]*string `json:"additionalConfig,omitempty"`
 
-	// KafkaAPISpec is client configuration for connecting to Redpanda brokers
+	// Defines client configuration for connecting to Redpanda brokers.
 	KafkaAPISpec *KafkaAPISpec `json:"kafkaApiSpec,omitempty"`
 
-	// MetricsNamespace can be used to overwrite fully-qualified
-	// name of the Metric. That should be easier to identify if
-	// multiple operator runs inside the same Kubernetes cluster.
+	// Overwrites the fully-qualified
+	// name of the metric. This should be easier to identify if
+	// multiple operator instances runs inside the same Kubernetes cluster.
 	// By default, it is set to `redpanda-operator`.
 	MetricsNamespace *string `json:"metricsNamespace,omitempty"`
 
-	// SynchronizationInterval when the topic controller will schedule next reconciliation
-	// Default is 3 seconds
+	// Defines when the topic controller will schedule the next reconciliation.
+	// Default is 3 seconds.
 	// +kubebuilder:validation:Type=string
 	// +kubebuilder:validation:Format=duration
 	// +kubebuilder:default="3s"
 	SynchronizationInterval *metav1.Duration `json:"interval,omitempty"`
 }
 
-// KafkaAPISpec represents definition for connection that used
-// Kafka protocol.
+// Configures client configuration settings for connecting to Redpanda brokers.
 type KafkaAPISpec struct {
+	// Specifies a list of broker addresses in the format <host>:<port>
 	Brokers []string `json:"brokers"`
+	// Defines TLS configuration settings for Redpanda clusters that have TLS enabled.
 	// +optional
 	TLS *KafkaTLS `json:"tls,omitempty"`
+	// Defines authentication configuration settings for Redpanda clusters that have authentication enabled.
 	// +optional
 	SASL *KafkaSASL `json:"sasl,omitempty"`
 }
 
-// KafkaSASL to connect to Kafka using SASL credentials
+// Configures credentials to connect to Redpanda cluster that has authenticaton enabled.
 type KafkaSASL struct {
+	// Specifies the username.
 	// +optional
 	Username string `json:"username,omitempty"`
+	// Specifies the password.
 	// +optional
 	Password  SecretKeyRef  `json:"passwordSecretRef,omitempty"`
+	// Specifies the SASL/SCRAM authentication mechanism.
 	Mechanism SASLMechanism `json:"mechanism"`
 	// +optional
 	OAUth KafkaSASLOAuthBearer `json:"oauth,omitempty"`
@@ -183,7 +188,7 @@ type KafkaSASLAWSMskIam struct {
 	UserAgent string `json:"userAgent"`
 }
 
-// KafkaTLS to connect to Kafka via TLS
+// Specifies TLS configuration settings for Redpanda clusters that have authentication enabled.
 type KafkaTLS struct {
 	// CaCert is the reference for certificate authority used to establish TLS connection to Redpanda
 	CaCert *SecretKeyRef `json:"caCertSecretRef,omitempty"`
@@ -196,7 +201,7 @@ type KafkaTLS struct {
 	InsecureSkipTLSVerify bool `json:"insecureSkipTlsVerify"`
 }
 
-// TopicStatus defines the observed state of Topic
+// Defines the observed state of the Topic resource.
 type TopicStatus struct {
 	// ObservedGeneration is the last observed generation of the Topic.
 	// +optional
@@ -269,21 +274,23 @@ type ConfigSynonyms struct {
 //+kubebuilder:object:root=true
 //+kubebuilder:subresource:status
 
-// Topic is the Schema for the topics API
+// Defines the CRD for Topic resources.
 type Topic struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
-
+	// Defines the desired state of the Topic resource.
 	Spec   TopicSpec   `json:"spec,omitempty"`
+	// Represents the current status of the Topic resource.
 	Status TopicStatus `json:"status,omitempty"`
 }
 
 //+kubebuilder:object:root=true
 
-// TopicList contains a list of Topic
+// TopicList contains a list of Topic objects.
 type TopicList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
+	// Specifies a list of Topic resources.
 	Items           []Topic `json:"items"`
 }
 

src/go/k8s/api/redpanda/v1alpha1/events_redpanda.go

@@ -1,15 +1,15 @@
 package v1alpha1
 
-// These constants define valid event severity values.
+// These constants define valid values for event severity levels.
 const (
-	// EventSeverityTrace represents a trace event, usually
-	// informing about actions taken during reconciliation.
+	// A trace event that usually
+	// informs you about actions taken during reconciliation.
 	EventSeverityTrace string = "trace"
-	// EventSeverityInfo represents an informational event, usually
-	// informing about changes.
+	// An informational event that usually
+	// informs you about changes.
 	EventSeverityInfo string = "info"
-	// EventSeverityError represent an error event, usually a warning
-	// that something goes wrong.
+	// An error event that usually warns you
+	// that something went wrong.
 	EventSeverityError string = "error"
 )
 

src/go/k8s/api/redpanda/v1alpha1/groupversion_info.go

@@ -7,7 +7,7 @@
 // the Business Source License, use of this software will be governed
 // by the Apache License, Version 2.0
 
-// Package v1alpha1 contains API Schema definitions for the redpanda v1alpha1 API group
+// This package defines the v1alpha1 schema for the Redpanda API. It is part of an evolving API architecture, representing an initial stage that may be subject to change based on user feedback and further development.
 // +kubebuilder:object:generate=true
 // +groupName=cluster.redpanda.com
 package v1alpha1
@@ -18,12 +18,12 @@ import (
 )
 
 var (
-	// GroupVersion is group version used to register these objects
+	// The group version used to register these objects.
 	GroupVersion = schema.GroupVersion{Group: "cluster.redpanda.com", Version: "v1alpha1"}
 
-	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	// SchemeBuilder is used to add Go types to the GroupVersionKind scheme.
 	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
 
-	// AddToScheme adds the types in this group-version to the given scheme.
+	// AddToScheme adds the types in this group version to the given scheme.
 	AddToScheme = SchemeBuilder.AddToScheme
 )