Merge pull request #1714 from marquiz/devel/api-document-fields

api/nfd: document all undocumented fields in the types

api/nfd/v1alpha1/types.go

@@ -28,6 +28,7 @@ type NodeFeatureList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata"`
 
+	// List of NodeFeatures.
 	Items []NodeFeature `json:"items"`
 }
 
@@ -40,6 +41,7 @@ type NodeFeature struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// Specification of the NodeFeature, containing features discovered for a node.
 	Spec NodeFeatureSpec `json:"spec"`
 }
 
@@ -72,6 +74,7 @@ type Features struct {
 //
 // +protobuf=true
 type FlagFeatureSet struct {
+	// Individual features of the feature set.
 	Elements map[string]Nil `json:"elements" protobuf:"bytes,1,rep,name=elements"`
 }
 
@@ -79,6 +82,7 @@ type FlagFeatureSet struct {
 //
 // +protobuf=true
 type AttributeFeatureSet struct {
+	// Individual features of the feature set.
 	Elements map[string]string `json:"elements" protobuf:"bytes,1,rep,name=elements"`
 }
 
@@ -86,6 +90,7 @@ type AttributeFeatureSet struct {
 //
 // +protobuf=true
 type InstanceFeatureSet struct {
+	// Individual features of the feature set.
 	Elements []InstanceFeature `json:"elements" protobuf:"bytes,1,rep,name=elements"`
 }
 
@@ -93,6 +98,7 @@ type InstanceFeatureSet struct {
 //
 // +protobuf=true
 type InstanceFeature struct {
+	// Attributes of the instance feature.
 	Attributes map[string]string `json:"attributes" protobuf:"bytes,1,rep,name=attributes"`
 }
 
@@ -108,6 +114,7 @@ type NodeFeatureRuleList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata"`
 
+	// List of NodeFeatureRules.
 	Items []NodeFeatureRule `json:"items"`
 }
 
@@ -122,6 +129,7 @@ type NodeFeatureRule struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// Spec defines the rules to be evaluated.
 	Spec NodeFeatureRuleSpec `json:"spec"`
 }
 
@@ -141,12 +149,17 @@ type NodeFeatureGroup struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   NodeFeatureGroupSpec   `json:"spec"`
+	// Spec defines the rules to be evaluated.
+	Spec NodeFeatureGroupSpec `json:"spec"`
+
+	// Status of the NodeFeatureGroup after the most recent evaluation of the
+	// specification.
 	Status NodeFeatureGroupStatus `json:"status,omitempty"`
 }
 
 // NodeFeatureGroupSpec describes a NodeFeatureGroup object.
 type NodeFeatureGroupSpec struct {
+	// List of rules to evaluate to determine nodes that belong in this group.
 	Rules []GroupRule `json:"featureGroupRules"`
 }
 
@@ -161,6 +174,7 @@ type NodeFeatureGroupStatus struct {
 }
 
 type FeatureGroupNode struct {
+	// Name of the node.
 	Name string `json:"name"`
 }
 
@@ -171,6 +185,7 @@ type NodeFeatureGroupList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata"`
 
+	// List of NodeFeatureGroups.
 	Items []NodeFeatureGroup `json:"items"`
 }
 

deployment/base/nfd-crds/nfd-api-crds.yaml

@@ -39,7 +39,8 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodeFeatureSpec describes a NodeFeature object.
+            description: Specification of the NodeFeature, containing features discovered
+              for a node.
             properties:
               features:
                 description: Features is the full "raw" features data that has been
@@ -53,6 +54,7 @@ spec:
                         elements:
                           additionalProperties:
                             type: string
+                          description: Individual features of the feature set.
                           type: object
                       required:
                       - elements
@@ -70,6 +72,7 @@ spec:
                             description: Nil is a dummy empty struct for protobuf
                               compatibility
                             type: object
+                          description: Individual features of the feature set.
                           type: object
                       required:
                       - elements
@@ -83,6 +86,7 @@ spec:
                         which is an instance having multiple attributes.
                       properties:
                         elements:
+                          description: Individual features of the feature set.
                           items:
                             description: InstanceFeature represents one instance of
                               a complex features, e.g. a device.
@@ -90,6 +94,7 @@ spec:
                               attributes:
                                 additionalProperties:
                                   type: string
+                                description: Attributes of the instance feature.
                                 type: object
                             required:
                             - attributes
@@ -155,9 +160,11 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodeFeatureGroupSpec describes a NodeFeatureGroup object.
+            description: Spec defines the rules to be evaluated.
             properties:
               featureGroupRules:
+                description: List of rules to evaluate to determine nodes that belong
+                  in this group.
                 items:
                   description: GroupRule defines a rule for nodegroup filtering.
                   properties:
@@ -356,6 +363,9 @@ spec:
             - featureGroupRules
             type: object
           status:
+            description: |-
+              Status of the NodeFeatureGroup after the most recent evaluation of the
+              specification.
             properties:
               nodes:
                 description: Nodes is a list of FeatureGroupNode in the cluster that
@@ -363,6 +373,7 @@ spec:
                 items:
                   properties:
                     name:
+                      description: Name of the node.
                       type: string
                   required:
                   - name
@@ -422,7 +433,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodeFeatureRuleSpec describes a NodeFeatureRule.
+            description: Spec defines the rules to be evaluated.
             properties:
               rules:
                 description: Rules is a list of node customization rules.

deployment/helm/node-feature-discovery/crds/nfd-api-crds.yaml

@@ -39,7 +39,8 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodeFeatureSpec describes a NodeFeature object.
+            description: Specification of the NodeFeature, containing features discovered
+              for a node.
             properties:
               features:
                 description: Features is the full "raw" features data that has been
@@ -53,6 +54,7 @@ spec:
                         elements:
                           additionalProperties:
                             type: string
+                          description: Individual features of the feature set.
                           type: object
                       required:
                       - elements
@@ -70,6 +72,7 @@ spec:
                             description: Nil is a dummy empty struct for protobuf
                               compatibility
                             type: object
+                          description: Individual features of the feature set.
                           type: object
                       required:
                       - elements
@@ -83,6 +86,7 @@ spec:
                         which is an instance having multiple attributes.
                       properties:
                         elements:
+                          description: Individual features of the feature set.
                           items:
                             description: InstanceFeature represents one instance of
                               a complex features, e.g. a device.
@@ -90,6 +94,7 @@ spec:
                               attributes:
                                 additionalProperties:
                                   type: string
+                                description: Attributes of the instance feature.
                                 type: object
                             required:
                             - attributes
@@ -155,9 +160,11 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodeFeatureGroupSpec describes a NodeFeatureGroup object.
+            description: Spec defines the rules to be evaluated.
             properties:
               featureGroupRules:
+                description: List of rules to evaluate to determine nodes that belong
+                  in this group.
                 items:
                   description: GroupRule defines a rule for nodegroup filtering.
                   properties:
@@ -356,6 +363,9 @@ spec:
             - featureGroupRules
             type: object
           status:
+            description: |-
+              Status of the NodeFeatureGroup after the most recent evaluation of the
+              specification.
             properties:
               nodes:
                 description: Nodes is a list of FeatureGroupNode in the cluster that
@@ -363,6 +373,7 @@ spec:
                 items:
                   properties:
                     name:
+                      description: Name of the node.
                       type: string
                   required:
                   - name
@@ -422,7 +433,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodeFeatureRuleSpec describes a NodeFeatureRule.
+            description: Spec defines the rules to be evaluated.
             properties:
               rules:
                 description: Rules is a list of node customization rules.