doc: add missing comments in API

Signed-off-by: Fred Rolland <[email protected]>

api/v1alpha1/hostdevicenetwork_types.go

@@ -60,7 +60,9 @@ type HostDeviceNetwork struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   HostDeviceNetworkSpec   `json:"spec,omitempty"`
+	// Defines the desired state of HostDeviceNetwork
+	Spec HostDeviceNetworkSpec `json:"spec,omitempty"`
+	// Defines the observed state of HostDeviceNetwork
 	Status HostDeviceNetworkStatus `json:"status,omitempty"`
 }
 

api/v1alpha1/ipoibnetwork_types.go

@@ -58,7 +58,9 @@ type IPoIBNetwork struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   IPoIBNetworkSpec   `json:"spec,omitempty"`
+	// Defines the desired state of IPoIBNetwork
+	Spec IPoIBNetworkSpec `json:"spec,omitempty"`
+	// Defines the observed state of IPoIBNetwork
 	Status IPoIBNetworkStatus `json:"status,omitempty"`
 }
 

api/v1alpha1/macvlannetwork_types.go

@@ -64,7 +64,9 @@ type MacvlanNetwork struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   MacvlanNetworkSpec   `json:"spec,omitempty"`
+	// Defines the desired state of MacvlanNetworkSpec
+	Spec MacvlanNetworkSpec `json:"spec,omitempty"`
+	// Defines the observed state of MacvlanNetwork
 	Status MacvlanNetworkStatus `json:"status,omitempty"`
 }
 

api/v1alpha1/nicclusterpolicy_types.go

@@ -72,6 +72,7 @@ func (is *ImageSpec) GetContainerResources() []ResourceRequirements {
 
 // ImageSpecWithConfig Contains ImageSpec and optional configuration
 type ImageSpecWithConfig struct {
+	// Image information for the component
 	ImageSpec `json:""`
 	// Configuration for the component as a string
 	Config *string `json:"config,omitempty"`
@@ -136,16 +137,18 @@ type DriverUpgradePolicySpec struct {
 	// +optional
 	// +kubebuilder:default:=1
 	// +kubebuilder:validation:Minimum:=0
-	MaxParallelUpgrades int                    `json:"maxParallelUpgrades,omitempty"`
-	WaitForCompletion   *WaitForCompletionSpec `json:"waitForCompletion,omitempty"`
-	DrainSpec           *DrainSpec             `json:"drain,omitempty"`
+	MaxParallelUpgrades int `json:"maxParallelUpgrades,omitempty"`
+	// The configuration for waiting on pods completions
+	WaitForCompletion *WaitForCompletionSpec `json:"waitForCompletion,omitempty"`
+	// The configuration for node drain during automatic upgrade
+	DrainSpec *DrainSpec `json:"drain,omitempty"`
 	// SafeLoad turn on safe driver loading (cordon and drain the node before loading the driver)
 	// +optional
 	// +kubebuilder:default:=false
 	SafeLoad bool `json:"safeLoad,omitempty"`
 }
 
-// WaitForCompletionSpec describes the configuration for waiting on job completions
+// WaitForCompletionSpec describes the configuration for waiting on pods completions
 type WaitForCompletionSpec struct {
 	// PodSelector specifies a label selector for the pods to wait for completion
 	// For more details on label selectors, see:
@@ -191,6 +194,7 @@ type DrainSpec struct {
 // 1. Image information for device plugin
 // 2. Device plugin configuration
 type DevicePluginSpec struct {
+	// Image information for the device plugin and optional configuration
 	ImageSpecWithConfig `json:""`
 	// Enables use of container device interface (CDI)
 	UseCdi bool `json:"useCdi,omitempty"`
@@ -201,6 +205,7 @@ type DevicePluginSpec struct {
 //  2. Multus CNI config if config is missing or empty then multus config will be automatically generated from the CNI
 //     configuration file of the master plugin (the first file in lexicographical order in cni-conf-dir)
 type MultusSpec struct {
+	// Image information for Multus and optional configuration
 	ImageSpecWithConfig `json:""`
 }
 
@@ -255,11 +260,13 @@ type IBKubernetesSpec struct {
 type NVIPAMSpec struct {
 	// Enable deployment of the validation webhook
 	EnableWebhook bool `json:"enableWebhook,omitempty"`
-	ImageSpec     `json:""`
+	// Image information for nv-ipam
+	ImageSpec `json:""`
 }
 
 // NICFeatureDiscoverySpec describes configuration options for nic-feature-discovery
 type NICFeatureDiscoverySpec struct {
+	// Image information for nic-feature-discovery
 	ImageSpec `json:""`
 }
 
@@ -273,6 +280,7 @@ type DOCATelemetryServiceConfig struct {
 
 // DOCATelemetryServiceSpec is the configuration for DOCA Telemetry Service.
 type DOCATelemetryServiceSpec struct {
+	// Image information for DOCA Telemetry Service
 	ImageSpec `json:""`
 	// +optional
 	// Config contains custom config for the DOCATelemetryService.
@@ -288,20 +296,30 @@ type NicClusterPolicySpec struct {
 	// Additional nodeAffinity rules to inject to the DaemonSets objects that are managed by the operator
 	NodeAffinity *v1.NodeAffinity `json:"nodeAffinity,omitempty"`
 	// Additional tolerations to inject to the DaemonSets objects that are managed by the operator
-	Tolerations            []v1.Toleration           `json:"tolerations,omitempty"`
-	OFEDDriver             *OFEDDriverSpec           `json:"ofedDriver,omitempty"`
-	RdmaSharedDevicePlugin *DevicePluginSpec         `json:"rdmaSharedDevicePlugin,omitempty"`
-	SriovDevicePlugin      *DevicePluginSpec         `json:"sriovDevicePlugin,omitempty"`
-	IBKubernetes           *IBKubernetesSpec         `json:"ibKubernetes,omitempty"`
-	SecondaryNetwork       *SecondaryNetworkSpec     `json:"secondaryNetwork,omitempty"`
-	NvIpam                 *NVIPAMSpec               `json:"nvIpam,omitempty"`
-	NicFeatureDiscovery    *NICFeatureDiscoverySpec  `json:"nicFeatureDiscovery,omitempty"`
-	DOCATelemetryService   *DOCATelemetryServiceSpec `json:"docaTelemetryService,omitempty"`
+	Tolerations []v1.Toleration `json:"tolerations,omitempty"`
+	// Configuration options for OFED driver
+	OFEDDriver *OFEDDriverSpec `json:"ofedDriver,omitempty"`
+	// Configuration options for RDMA shared device plugin
+	RdmaSharedDevicePlugin *DevicePluginSpec `json:"rdmaSharedDevicePlugin,omitempty"`
+	// Configuration options for SRIOV device plugin
+	SriovDevicePlugin *DevicePluginSpec `json:"sriovDevicePlugin,omitempty"`
+	// Configuration options for ib-kubernetes
+	IBKubernetes *IBKubernetesSpec `json:"ibKubernetes,omitempty"`
+	// Configuration options for secondary network
+	SecondaryNetwork *SecondaryNetworkSpec `json:"secondaryNetwork,omitempty"`
+	// Configuration options for nv-ipam
+	NvIpam *NVIPAMSpec `json:"nvIpam,omitempty"`
+	// Configuration options for nic-feature-discovery
+	NicFeatureDiscovery *NICFeatureDiscoverySpec `json:"nicFeatureDiscovery,omitempty"`
+	// Configuration options for DOCA Telemetry Service
+	DOCATelemetryService *DOCATelemetryServiceSpec `json:"docaTelemetryService,omitempty"`
 }
 
 // AppliedState defines a finer-grained view of the observed state of NicClusterPolicy
 type AppliedState struct {
+	// Name of the deployed component this state refers to
 	Name string `json:"name"`
+	// The state of the deployed component. ("ready", "notReady", "ignore", "error")
 	// +kubebuilder:validation:Enum={"ready", "notReady", "ignore", "error"}
 	State State `json:"state"`
 	// Message is a human readable message indicating details about why
@@ -335,7 +353,9 @@ type NicClusterPolicy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   NicClusterPolicySpec   `json:"spec,omitempty"`
+	// Defines the desired state of NicClusterPolicy
+	Spec NicClusterPolicySpec `json:"spec,omitempty"`
+	// Defines the observed state of NicClusterPolicy
 	Status NicClusterPolicyStatus `json:"status,omitempty"`
 }
 

config/crd/bases/mellanox.com_hostdevicenetworks.yaml

@@ -44,7 +44,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: HostDeviceNetworkSpec defines the desired state of HostDeviceNetwork
+            description: Defines the desired state of HostDeviceNetwork
             properties:
               ipam:
                 description: IPAM configuration to be used for this network
@@ -57,7 +57,7 @@ spec:
                 type: string
             type: object
           status:
-            description: HostDeviceNetworkStatus defines the observed state of HostDeviceNetwork
+            description: Defines the observed state of HostDeviceNetwork
             properties:
               appliedStates:
                 description: AppliedStates provide a finer view of the observed state
@@ -71,9 +71,12 @@ spec:
                         the state is in this condition
                       type: string
                     name:
+                      description: Name of the deployed component this state refers
+                        to
                       type: string
                     state:
-                      description: State represents reconcile state of the system.
+                      description: The state of the deployed component. ("ready",
+                        "notReady", "ignore", "error")
                       enum:
                       - ready
                       - notReady

config/crd/bases/mellanox.com_ipoibnetworks.yaml

@@ -44,7 +44,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: IPoIBNetworkSpec defines the desired state of IPoIBNetwork
+            description: Defines the desired state of IPoIBNetwork
             properties:
               ipam:
                 description: IPAM configuration to be used for this network.
@@ -58,7 +58,7 @@ spec:
                 type: string
             type: object
           status:
-            description: IPoIBNetworkStatus defines the observed state of IPoIBNetwork
+            description: Defines the observed state of IPoIBNetwork
             properties:
               ipoibNetworkAttachmentDef:
                 description: Network attachment definition generated from IPoIBNetworkSpec

config/crd/bases/mellanox.com_macvlannetworks.yaml

@@ -44,7 +44,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: MacvlanNetworkSpec defines the desired state of MacvlanNetwork
+            description: Defines the desired state of MacvlanNetworkSpec
             properties:
               ipam:
                 description: IPAM configuration to be used for this network.
@@ -72,7 +72,7 @@ spec:
                 type: string
             type: object
           status:
-            description: MacvlanNetworkStatus defines the observed state of MacvlanNetwork
+            description: Defines the observed state of MacvlanNetwork
             properties:
               macvlanNetworkAttachmentDef:
                 description: Network attachment definition generated from MacvlanNetworkSpec

config/crd/bases/mellanox.com_nicclusterpolicies.yaml

@@ -44,11 +44,10 @@ spec:
           metadata:
             type: object
           spec:
-            description: NicClusterPolicySpec defines the desired state of NicClusterPolicy
+            description: Defines the desired state of NicClusterPolicy
             properties:
               docaTelemetryService:
-                description: DOCATelemetryServiceSpec is the configuration for DOCA
-                  Telemetry Service.
+                description: Configuration options for DOCA Telemetry Service
                 properties:
                   config:
                     description: |-
@@ -126,8 +125,7 @@ spec:
                 - version
                 type: object
               ibKubernetes:
-                description: IBKubernetesSpec describes configuration options for
-                  ib-kubernetes
+                description: Configuration options for ib-kubernetes
                 properties:
                   containerResources:
                     description: ResourceRequirements describes the compute resource
@@ -208,8 +206,7 @@ spec:
                 - version
                 type: object
               nicFeatureDiscovery:
-                description: NICFeatureDiscoverySpec describes configuration options
-                  for nic-feature-discovery
+                description: Configuration options for nic-feature-discovery
                 properties:
                   containerResources:
                     description: ResourceRequirements describes the compute resource
@@ -465,10 +462,7 @@ spec:
                     x-kubernetes-map-type: atomic
                 type: object
               nvIpam:
-                description: |-
-                  NVIPAMSpec describes configuration options for nv-ipam
-                  1. Image information for nv-ipam
-                  2. Configuration for nv-ipam
+                description: Configuration options for nv-ipam
                 properties:
                   containerResources:
                     description: ResourceRequirements describes the compute resource
@@ -538,8 +532,7 @@ spec:
                 - version
                 type: object
               ofedDriver:
-                description: OFEDDriverSpec describes configuration options for OFED
-                  driver
+                description: Configuration options for OFED driver
                 properties:
                   certConfig:
                     description: 'Optional: Custom TLS certificates configuration
@@ -794,8 +787,8 @@ spec:
                           if set to false all other options are ignored
                         type: boolean
                       drain:
-                        description: DrainSpec describes configuration for node drain
-                          during automatic upgrade
+                        description: The configuration for node drain during automatic
+                          upgrade
                         properties:
                           deleteEmptyDir:
                             default: false
@@ -839,8 +832,7 @@ spec:
                           and drain the node before loading the driver)
                         type: boolean
                       waitForCompletion:
-                        description: WaitForCompletionSpec describes the configuration
-                          for waiting on job completions
+                        description: The configuration for waiting on pods completions
                         properties:
                           podSelector:
                             description: |-
@@ -867,10 +859,7 @@ spec:
                 - version
                 type: object
               rdmaSharedDevicePlugin:
-                description: |-
-                  DevicePluginSpec describes configuration options for device plugin
-                  1. Image information for device plugin
-                  2. Device plugin configuration
+                description: Configuration options for RDMA shared device plugin
                 properties:
                   config:
                     description: Configuration for the component as a string
@@ -943,8 +932,7 @@ spec:
                 - version
                 type: object
               secondaryNetwork:
-                description: SecondaryNetworkSpec describes configuration options
-                  for secondary network
+                description: Configuration options for secondary network
                 properties:
                   cniPlugins:
                     description: Image information for CNI plugins
@@ -1219,10 +1207,7 @@ spec:
                     type: object
                 type: object
               sriovDevicePlugin:
-                description: |-
-                  DevicePluginSpec describes configuration options for device plugin
-                  1. Image information for device plugin
-                  2. Device plugin configuration
+                description: Configuration options for SRIOV device plugin
                 properties:
                   config:
                     description: Configuration for the component as a string
@@ -1336,7 +1321,7 @@ spec:
                 type: array
             type: object
           status:
-            description: NicClusterPolicyStatus defines the observed state of NicClusterPolicy
+            description: Defines the observed state of NicClusterPolicy
             properties:
               appliedStates:
                 description: AppliedStates provide a finer view of the observed state
@@ -1350,9 +1335,12 @@ spec:
                         the state is in this condition
                       type: string
                     name:
+                      description: Name of the deployed component this state refers
+                        to
                       type: string
                     state:
-                      description: State represents reconcile state of the system.
+                      description: The state of the deployed component. ("ready",
+                        "notReady", "ignore", "error")
                       enum:
                       - ready
                       - notReady

deployment/network-operator/crds/mellanox.com_hostdevicenetworks.yaml

@@ -44,7 +44,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: HostDeviceNetworkSpec defines the desired state of HostDeviceNetwork
+            description: Defines the desired state of HostDeviceNetwork
             properties:
               ipam:
                 description: IPAM configuration to be used for this network
@@ -57,7 +57,7 @@ spec:
                 type: string
             type: object
           status:
-            description: HostDeviceNetworkStatus defines the observed state of HostDeviceNetwork
+            description: Defines the observed state of HostDeviceNetwork
             properties:
               appliedStates:
                 description: AppliedStates provide a finer view of the observed state
@@ -71,9 +71,12 @@ spec:
                         the state is in this condition
                       type: string
                     name:
+                      description: Name of the deployed component this state refers
+                        to
                       type: string
                     state:
-                      description: State represents reconcile state of the system.
+                      description: The state of the deployed component. ("ready",
+                        "notReady", "ignore", "error")
                       enum:
                       - ready
                       - notReady