Update CRD descriptions

ref: https://issues.redhat.com/browse/ACM-8992
Signed-off-by: Dale Haiducek <19750917+dhaiducek@users.noreply.github.com>

api/v1beta1/operatorpolicy_types.go

@@ -10,100 +10,129 @@ import (
 	policyv1 "open-cluster-management.io/config-policy-controller/api/v1"
 )
 
-// StatusConfigAction : StatusMessageOnly or NonCompliant
-// +kubebuilder:validation:Enum=StatusMessageOnly;NonCompliant
-type StatusConfigAction string
-
-// RemovalAction : Keep, Delete, or DeleteIfUnused
+// RemovalAction is the behavior when the operator policy is removed. Options are 'Keep', 'Delete',
+// or 'DeleteIfUnused'.
+//
 // +kubebuilder:validation:Enum=Keep;Delete;DeleteIfUnused
 type RemovalAction string
 
 const (
-	// StatusMessageOnly is a StatusConfigAction that only shows the status message
-	StatusMessageOnly StatusConfigAction = "StatusMessageOnly"
-	// NonCompliant is a StatusConfigAction that shows the status message and sets
-	// the compliance to NonCompliant
-	NonCompliant StatusConfigAction = "NonCompliant"
-)
-
-const (
-	// Keep is a RemovalBehavior indicating that the controller may not delete a type
+	// Keep is a RemovalBehavior indicating that the controller may not delete a type.
 	Keep RemovalAction = "Keep"
-	// Delete is a RemovalBehavior indicating that the controller may delete a type
+
+	// Delete is a RemovalBehavior indicating that the controller may delete a type.
 	Delete RemovalAction = "Delete"
-	// DeleteIfUnused is a RemovalBehavior indicating that the controller may delete
-	// a type only if is not being used by another subscription
+
+	// DeleteIfUnused is a RemovalBehavior indicating that the controller may delete a type only if it
+	// is not being used by another subscription.
 	DeleteIfUnused RemovalAction = "DeleteIfUnused"
 )
 
-// RemovalBehavior defines resource behavior when policy is removed
+// RemovalBehavior defines resource behavior when the operator policy is removed.
 type RemovalBehavior struct {
-	// Kind OperatorGroup
+	// OperatorGroups is the removal action for kind OperatorGroup.
 	OperatorGroups RemovalAction `json:"operatorGroups,omitempty"`
-	// Kind Subscription
+
+	// Subscriptions is the removal action for kind Subscription.
 	Subscriptions RemovalAction `json:"subscriptions,omitempty"`
-	// Kind ClusterServiceVersion
+
+	// CSVs is the removal action for kind ClusterServiceVersion.
 	CSVs RemovalAction `json:"clusterServiceVersions,omitempty"`
-	// Kind InstallPlan
+
+	// InstallPlan is the removal action for kind InstallPlan.
 	InstallPlan RemovalAction `json:"installPlans,omitempty"`
-	// Kind CustomResourceDefinitions
+
+	// CRDs is the removal action for kind CustomResourceDefinition.
 	CRDs RemovalAction `json:"customResourceDefinitions,omitempty"`
-	// Kind APIServiceDefinitions
+
+	// APIServiceDefinitions is the removal action for kind APIServices that have been defined in the
+	// associated ClusterServiceVersion.
 	APIServiceDefinitions RemovalAction `json:"apiServiceDefinitions,omitempty"`
 }
 
-// StatusConfig defines how resource statuses affect the OperatorPolicy status and compliance
+// StatusConfigAction configures how a status condition is reported when the involved operators are
+// out of compliance with the operator policy. Options are 'StatusMessageOnly' or
+// 'NonCompliant'.
+//
+// +kubebuilder:validation:Enum=StatusMessageOnly;NonCompliant
+type StatusConfigAction string
+
+const (
+	// StatusMessageOnly is a StatusConfigAction that only shows the status message.
+	StatusMessageOnly StatusConfigAction = "StatusMessageOnly"
+
+	// NonCompliant is a StatusConfigAction that shows the status message and sets the compliance to
+	// NonCompliant.
+	NonCompliant StatusConfigAction = "NonCompliant"
+)
+
+// StatusConfig defines how resource statuses affect the overall operator policy status and
+// compliance.
 type StatusConfig struct {
+	// CatalogSourcesUnhealthy defines how the CatalogSourcesUnhealthy condition affects the operator
+	// policy status.
 	CatalogSourceUnhealthy StatusConfigAction `json:"catalogSourceUnhealthy,omitempty"`
+
+	// DeploymentsUnavailable defines how the DeploymentsUnavailable condition affects the operator
+	// policy status.
 	DeploymentsUnavailable StatusConfigAction `json:"deploymentsUnavailable,omitempty"`
-	UpgradesAvailable      StatusConfigAction `json:"upgradesAvailable,omitempty"`
-	UpgradesProgressing    StatusConfigAction `json:"upgradesProgressing,omitempty"`
+
+	// UpgradesAvailable defines how the UpgradesAvailable condition affects the operator policy
+	// status.
+	UpgradesAvailable StatusConfigAction `json:"upgradesAvailable,omitempty"`
+
+	// UpgradesProgressing defines how the UpgradesProgressing condition affects the operator policy
+	// status.
+	UpgradesProgressing StatusConfigAction `json:"upgradesProgressing,omitempty"`
 }
 
-// OperatorPolicySpec defines the desired state of OperatorPolicy
+// OperatorPolicySpec defines the desired state of a particular operator on the cluster.
 type OperatorPolicySpec struct {
-	Severity          policyv1.Severity          `json:"severity,omitempty"`          // low, medium, high
-	RemediationAction policyv1.RemediationAction `json:"remediationAction,omitempty"` // inform, enforce
-	ComplianceType    policyv1.ComplianceType    `json:"complianceType"`              // musthave
-
-	// Include the name, namespace, and any `spec` fields for the OperatorGroup.
-	// For more info, see `kubectl explain operatorgroup.spec` or
-	// https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/
+	Severity          policyv1.Severity          `json:"severity,omitempty"`
+	RemediationAction policyv1.RemediationAction `json:"remediationAction,omitempty"`
+	ComplianceType    policyv1.ComplianceType    `json:"complianceType"`
+
+	// OperatorGroup specifies the OperatorGroup to be handled. Include the name, namespace, and any
+	// `spec` fields for the OperatorGroup. For more info, see `kubectl explain operatorgroups.spec`
+	// or view https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/
+	//
 	// +kubebuilder:pruning:PreserveUnknownFields
 	// +optional
 	OperatorGroup *runtime.RawExtension `json:"operatorGroup,omitempty"`
 
-	// Include the namespace, and any `spec` fields for the Subscription.
-	// For more info, see `kubectl explain subscription.spec` or
+	// Subscription specifies the operator Subscription to be handled. Include the namespace, and any
+	// `spec` fields for the Subscription. For more info, see `kubectl explain
+	// subscriptions.operators.coreos.com.spec` or view
 	// https://olm.operatorframework.io/docs/concepts/crds/subscription/
-	// +kubebuilder:validation:Required
+	//
 	// +kubebuilder:pruning:PreserveUnknownFields
 	Subscription runtime.RawExtension `json:"subscription"`
 
-	// Versions is a list of nonempty strings that specifies which installed versions are compliant when
-	// in 'inform' mode, and which installPlans are approved when in 'enforce' mode
+	// Versions is a list of nonempty strings that specifies which installed versions are compliant
+	// when in 'inform' mode and which InstallPlans are approved when in 'enforce' mode.
 	Versions []policyv1.NonEmptyString `json:"versions,omitempty"`
-
-	// FUTURE
-	//nolint:dupword
-	// RemovalBehavior RemovalBehavior           `json:"removalBehavior,omitempty"`
-	//nolint:dupword
-	// StatusConfig    StatusConfig              `json:"statusConfig,omitempty"`
 }
 
-// OperatorPolicyStatus defines the observed state of OperatorPolicy
+// OperatorPolicyStatus reports the observed state of the operators resulting from the
+// specifications given in the operator policy.
 type OperatorPolicyStatus struct {
-	// Most recent compliance state of the policy
+	// ComplianceState reports the most recent compliance state of the operator policy.
 	ComplianceState policyv1.ComplianceState `json:"compliant,omitempty"`
-	// Historic details on the condition of the policy
+
+	// Conditions reports historic details on the condition of the operator policy.
+	//
 	// +listType=map
 	// +listMapKey=type
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
-	// List of resources processed by the policy
+
+	// RelatedObjects reports a list of resources associated with the operator policy.
+	//
 	// +optional
 	RelatedObjects []policyv1.RelatedObject `json:"relatedObjects"`
 }
 
+// RelatedObjsOfKind iterates over the related objects in the status and returns a map of the index
+// in the array to the related object that has the given kind.
 func (status OperatorPolicyStatus) RelatedObjsOfKind(kind string) map[int]policyv1.RelatedObject {
 	objs := make(map[int]policyv1.RelatedObject)
 
@@ -116,9 +145,9 @@ func (status OperatorPolicyStatus) RelatedObjsOfKind(kind string) map[int]policy
 	return objs
 }
 
-// Searches the conditions of the policy, and returns the index and condition matching the
-// given condition Type. It will return -1 as the index if no condition of the specified
-// Type is found.
+// GetCondition iterates over the status conditions of the policy and returns the index and
+// condition matching the given condition Type. It will return -1 as the index if no condition of
+// the specified Type is found.
 func (status OperatorPolicyStatus) GetCondition(condType string) (int, metav1.Condition) {
 	for i, cond := range status.Conditions {
 		if cond.Type == condType {
@@ -129,10 +158,12 @@ func (status OperatorPolicyStatus) GetCondition(condType string) (int, metav1.Co
 	return -1, metav1.Condition{}
 }
 
-//+kubebuilder:object:root=true
-//+kubebuilder:subresource:status
-
-// OperatorPolicy is the Schema for the operatorpolicies API
+// OperatorPolicy is the Schema for the operatorpolicies API. Operator policy eases the management
+// of OLM operators by providing automation for their management and reporting on the status across
+// the various operator objects.
+//
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
 type OperatorPolicy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -141,9 +172,9 @@ type OperatorPolicy struct {
 	Status OperatorPolicyStatus `json:"status,omitempty"`
 }
 
-//+kubebuilder:object:root=true
-
-// OperatorPolicyList contains a list of OperatorPolicy
+// OperatorPolicyList contains a list of operator policies.
+//
+// +kubebuilder:object:root=true
 type OperatorPolicyList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`